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This book describes the internal logic of the catalog management routines and 
provides diagnostic information. This information is directed to maintenance 
personnel and development programmers who require an in-depth knowledge of 
the program’s design, organization, and data areas. It is not required for effective 
use of catalog management facilities. 


You should be familiar with general programming techniques, OS/VS concepts 
and use, and System/370 before reading this book. If you are unfamiliar with 
the general concepts of catalog management, read: 


OS/VS Data Management Services Guide, GC28-3783, for the general 
concepts of data sets and catalog management. 


OS/VS VSAM Programmer’s Guide, GC26-3806, for the general concepts of 
VSAM data sets and catalog management. 


OS/VS Utilities, GC35-0005, for information about IEHPROGM and generation 
data groups. 


OS/VS Data Management for System Programmers, GC28-0631, to see how 
catalog-management routines are invoked. 


Other books that may be helpful to you are: 


OS/VS1 Debugging Guide, GC24-5093, which describes how to analyze a 
main storage dump from OS/VS1. 


OS/VS Service Aids, GC28-0633, which describes several service aids and 
programs available under the operating system (notably for this book, 
HMASPZAP). 


OS/VS DADSM Logic, GY26-3787, which provides details about module 
1GG0553A and rotational positioning support (RPS). 


OS/VS SAM Logic, GY26-3788, which provides details about the BLDL 
routine. 


OS/VS VSAM Logic, SY26-3805, which provides the internal logic of the VSAM 
catalog routines, and describes the VSAM parameter list. 


OS/VSI System Data Areas, S¥Y28-0605, which shows the content of most of 
the operating system control blocks and tables. 


This book is divided into six chapters and a glossary: 


‘Introduction”’ describes what the catalog is, how the catalog is structured, 
and how the catalog-management routines are invoked. The chapter defines 
terms that are used throughout the book. 


“Method of Operation” provides the design overview. This chapter describes 
the philosophy behind the programs. Emphasis is on the flow of data and the 
concepts of catalog management, rather than on the organization of the 
modules. 


“Program Organization” describes each module of catalog management and 
identifies the specific function that each performs to achieve the catalog 
management objectives. This chapter shows the logical flow from module to 
module and contains the flowcharts of the modules. 


‘Microfiche Directory” contains a table that relates the information in this 
book to the listings on microfiche. 
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e ‘Data Areas” describes the record formats and work areas that are used by 
catalog management. 


e ‘Diagnostic Aids” can help you when you’re diagnosing a problem. This 
chapter shows how to dump and analyze the catalog, and how to determine 
what modules are used for a particular case. 





e “Glossary” of terms and acronyms used in this publication is found just before 
the index. 
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Introduction 


Cc Catalog management is the part of OS/VS that enables a user to locate a data set 
by specifying only a data set name. Catalog management stores data set names 
with volume and device information in a catalog, itself a data set named 
SYSCTLG. In use, the name in the user’s request is correlated with the 
appropriate volume identification. The catalog-management routines organize the 
catalog by inserting, removing, and locating entries in the catalog, and by 
formatting new catalogs. 


Catalog management is a type 4 Svc. Under VS1, the catalog-management 
routines execute in the 1024-byte transient areas of the operating system nucleus. 
| System and machine requirements are those of the operating system. 


This chapter discusses the catalog, illustrates several examples of a catalog, and 
discusses how the catalog-management routines are invoked. 


SYSCTLG Data Set 


The catalog is always named SYSCTLG; thus, there can be only one OS/VS 
catalog on any one volume. 


SYSCTLG data sets are formatted like partitioned data set (PDS) directories. Each 
physical block consists of an 8-byte key and a 256-byte data record. The format 
of the logical records contained in the physical block is shown in the chapter 
‘Data Areas,” page 61. 


Names and Indexes 


C Every cataloged data set has a name; this name can be a simple name ora 
qualified name. 


A simple name is a collection of up to eight EBCDIC characters. A qualified 
name is a string of names, separated by periods. The last name in the string is a 
simple name; the preceding names are qualifiers. Each qualifier can be up to 
eight characters long; the maximum total length of a qualified name is 44 
characters, including the separating periods. 


Each qualifier of a data set name corresponds to one index in the catalog. The 
structure of these indexes forms the catalog. The simple name of a data set is 
found in the lowest level of structure corresponding to the fully qualified name. 
The highest level of the catalog is called the volume index; the volume index is 
automatically built the first time a new catalog is used by the catalog 
management routines. 


Names in an index level are arranged in EBCDIC collating sequence. 


Each physical block of SYSCTLG can contain only one index level. An index 
level, however, can span more than one block. Multiple blocks of one index are 
chained together with the last logical record in each block. Contiguous blocks 
make use of the key to speed searching. 


: Figure 1 shows an example of a catalog containing only the volume index and 
one simple name. (We will build on this figure throughout this chapter.) As with 
any data set on a direct access volume, SYSCTLG is found by tracing through the 
Volume Label to the Volume Table of Contents (VTOC). The VTOC contains a 

.: Data Set Control Block (DSCB) for each data set on that volume (independent of 
whether that data set is cataloged). The Format 1 DSCB for SYSCTLG points to 
the catalog data set. 
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The catalog data set is shown as the shaded block in Figure 1. The first record 
of SYSCTLG contains the volume index. The entry in that volume index identifies 
the device type and serial number for the volume that contains the data set 


ALPHA. 
Figure 2 shows a qualified name in the catalog. Cataloging the data set BETA.B.C | 
adds another entry to the volume index. This entry points to the BETA index, | 





which contains an entry for B. Following the pointer to the B index, we find an 
entry for C, which identifies the volume containing data set BETA.B.C. 















DSCB to 
SYSCTLG 
Data Set 


a Device Type and 
74 Serial No. of 
Volume Containing 
Data Set ALPHA 











Figure 1. Example of a Catalog with One Simple Name 


‘| Address of 
‘| first Block of 
Index BETA 





SYSCTLG ries ge 


Device Type and 
Serial No. of 
Valume Containing 
Data Set BETA.B.C 


Figure 2. Example of a Catalog with a Qualified Name 
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Control Volumes 


Aliases 


Generation Data Groups 


Any direct access volume supported by OS/VS may contain a catalog. A volume 
that contains a catalog is called a control volume (CVOL). The system residence 
volume always contains a catalog. 


A user specifies which CVOL contains the catalog (perhaps by allowing the 
default to the system residence volume). For a data set to be available through 
the catalog, its name must appear in either the catalog on the specified CVOL or 
in a CVOL that is connected to the specified CVOL. When a CVOL is connected, 
there is a pointer in the volume index of the catalog on the specified CVOL. This 
identifies the connected CVOL and names a high-level index on the connected 
CVOL. 


A search for a data set may start on the system residence volume; a CVOL 
pointer on the system residence volume can direct the search to a connected 
CVOL. The search starts again on the connected CVOL, using the fully qualified 
name in the CVOL’s SYSCTLG data set. The search may alternately be started on 
a CVOL other than the system residence volume, as directed by the user. 


Figure 3 shows a CVOL pointer in the catalog. This CVOL pointer connects 
another CVOL to this catalog. In Figure 3, an entry for Y has been placed in the 
volume index. This entry identifies the volume that contains the name Y in the 
volume index of its catalog. 





Address of first 
block of Index 
BETA, for which 
X is an Alias 


SYSCTLG 







volame aLPHa| | | BETA | 


Index 








Device Type and 
Ser, No. of : 
Volume Containing 
Name "Y” in its 
Volume Index 





Figure 3. Example of a Catalog with an Alias and a Connected CVOL 


An alias is an alternative name for the highest-level index in a qualified data set 
name. There can be as many as 255 aliases to the first component of a qualified 
name. 


Figure 3 also shows an alias entry. Here the name X is an alias for BETA, so an 
entry for X is placed in the volume index. The entry for BETA and the entry for 
X both point to index BETA. Note that only the high-level name can have an 
alias. P 


A generation data group (GDG) is a collection of data sets that have a common 
external name, and that are related by the time sequence in which they were 
cataloged (that is, their generation). For example, a data set named 
LAB.PAYROLL(0) refers to the most recent data set of the group; 
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Entries of a Catalog 





LAB.PAYROLL(-1) refers to the second most recent data set, etc. The number in 
parentheses is called the relative number of a specific generation. 


The relative number relates to an absolute name for that generation of the data 

set. The absolute name is the simple name of the data set. The absolute name 

has the general form GannnV mm, where nnnn is the generation number, and 

mm is the version number. The last qualifier in a relative GDG name is the 

name of the generation index. The generation number in the absolute name is Jo 
complemented before the name is added to the generation index, so the most ) 
recent name (highest generation number) is the first entry in the index. 


Figure 4 shows a generation data group in the catalog. In this example, the 
external data set name BETA.B.F applies to a generation data group, consisting of 
generations of the same data set. Here the lowest qualifying name, F, does not 
point to the data set, but rather points to the generation index. This generation 
index consists of pointers to generations of the data set group BETA.B.F. 


The logical records of the SYSCTLG data set are called entries. These entries are 
linked together to form indexes and to connect indexes together. Figure 5 shows 
and names each type of entry. 


Each index contains one control entry and any number of pointer entries. The 
control entry, which is the first entry on each index, identifies that index. Other 
index entries link blocks of one index together, point to lower indexes, and point 
to data sets. 

















SYSCTLG 


: % 










"Volume | 
Index [avena| || eer | 
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Pé Address of First 
| / | Block of Generation 






Index (Index F) 
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Figure 4. Example of a Catalog with a Generation Data Group 
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Entry Name Abbreviation Description 


Alias entry AE Contains an alternate name for the high-level 
qualifier of a data set name. 


Control volume CVPE Connects another control volume (CVQL) to this 
pointer entry CVOL; contains a name that appears in the volume 
index of the connected CVOL. 


Data set pointer DSPE Contains the simple name of a data set and 

entry provides the location of this data set. 

Generation index GIPE Points to the lowest index for a generation 

pointer entry data group. 

Index control ICE First entry of all indexes other than volume index; 

entry describes the index level for one qualifier of a data 
set name. 

Index link entry ILE Links this block to the next block in a chain of 
blocks for one index. 

Index pointer IPE Points to a lower-level index of this name. 

entry 

Volume control VCB A block of the catalog that contains the volume 

block list for a data set that resides on more than five 
volumes. 

Volume control VCBPE Points to a volume control block. 


block pointer entry 


Volume index VICE The first entry in the volume index (the 

control entry highest-level index in the catalog); describes the 
volume index and controls allocation of space in 
the catalog on one volume. 


Figure 5. Kinds of Entries in the Catalog 


Using the Catalog Management Routines 


Introduction 


Catalog management routines are invoked by the utility IEHPROGM, the job 


| scheduler, or by macro statements in an Assembler language program. 


IEHPROGM creates and deletes indexes, aliases, and generation indexes, and it 
catalogs and uncatalogs data sets according to specifications supplied by the user 
of IEHPROGM. 


The job scheduler calls the catalog management routines when it must locate a 
data set, given only its name, or when the DISP parameter of a DD statement 
implies catalog action. 


All of these invocations of catalog management are produced by using three 
macro instructions: LOCATE, CATALOG, and INDEX. These macros generate a 
reference to a parameter list (produced by the CAMLST macro) and an SVC 26 
instruction. 


One of the operands of the CAMLST macro instruction specifies the function to 
be performed. These functions are categorized as locate functions or non-locate 
functions. The locate functions are those that require read-only operations to the 
catalog (that is, the catalog is not changed). The non-locate functions are those 
that do require changes to the catalog. 


The locate functions are: 
e NAME, which locates a data set by name. 


e BLOCK, which locates a block of SYSCTLG. 
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The non-locate functions are: 


BLDX, which creates one index level. 

BLDG, which creates a generation index. 

BLDA, which assigns an alias to an existing high-level name. 
DLTX, which deletes one index level. 

DLTA, which deletes an alias. 

LNKX, which connects a CVOL. 

DRPX, which disconnects a CVOL. 

CAT, which adds a data set name to the catalog. 


CATBX, which adds a data set name to the catalog and creates any missing 
index levels. 


UNCAT, which removes a data set name from the catalog. 


UCATDX, which removes a data set name from the catalog and deletes index 
levels that are no longer needed (except the high-level index). 


RECAT, which recatalogs a data set. 


For more information about the use of a catalog, see OS/VS Data Management 
for System Programmers, GC28-0631 (the first chapter), or OS/VS Utilities, 
GC35-0005 (the section on IEHPROGM). 


For more information about generation data groups, see OS/VS Data 
Management Services, GC28-3783. 
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Method of Operation 


Operation |, Read 


This chapter explains the design of catalog management. 


In its simplest form, catalog management consists of three operations: read, 
setup, and:write. Figure 6 illustrates this overview. Input to catalog management 
is shown in the block on the left, processing is shown in the center block, and 
output from catalog management is shown in the block to the right. The three 
operations are shown in the process block. 


VS input to catalog management consists of a parameter list built by the calier 
with the CAMLST macro instruction, supervisor control blocks, and the existing 
catalog. The output from catalog management depends on the requested 
function. Locate functions result in a volume list returned in the caller’s area. 
Non-locate functions result in an updated catalog. 


VSAM input consists of a similar parameter list. For a description of the VSAM 
parameter list, see the chapter ‘Data Areas” in OS/VS VSAM Logic , SY26-3805. 


When only the OS/VS catalog is present, catalog management, specifically 
Controller I, translates the VSAM input into CAMLST form. VSAM Superlocate, an 
internal Scheduler interface, is the only valid translatable list in Controller I. 
Output is translated to VSAM format. 


When both the OS/VS and VSAM catalog are present, Controller II directs activity 
to the appropriate catalog and translates as required. Duplicate entry checking is 
always done to prevent a catalog entry from existing in both the OS/VS and 
VSAM Catalog. 


For a locate function, only the read operation is required. For a non-locate 
function, the read operation is used to locate the catalog block to which a change 
is to be made. The setup operation determines how the change is to be made, 
and the write operation updates the catalog accordingly. 


The CATBX function is slightly more complex; it requires that setup and write be 
executed several times. I’ll discuss that function in more detail after describing 
each of the operations. 


Figure 7 illustrates the concepts of Operation I, Read. The input is that shown 
earlier in the overview. The caller’s parameter list includes a function request, 
points to a data set name, and identifies the CVOL to use (possibly the system 
residence volume by default). If a function is a locate function, an area in the 
caller’s module is made available for use as a return buffer. The usual SVC 
linkage for a type 3 SVC or type 4 SVC (catalog management is a type 4 SVC) 
provides pointers to several system control blocks. The VTOC of the CVOL is 
read to find the SYSCTLG data set and open it. 


Operation I begins by routing—actually pre-processing—the request to the OS/VS 
or VSAM Catalog. 


In a one-catalog system, OS/VS only, VSAM Superlocate requests are translated 
and honored by Controller I. 
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In a two-catalog system, OS/VS and VSAM, Controller II routes locate-by-name 
requests as follows: 


# of Start 

Crlgs Parm Cilg 
Case to Search List Search 
0 2 OS/VS VSAM 
| 2 VSAM VSAM 
2 | OS/VS VSAM 
3 I VSAM VSAM 
4 2 OS/VS OS/VS 
6 I OS/VS OS/VS 


The case is determined by the decimal equivalent of the last three bits in 
CAMOPTN3 of the CAMLST (see page 67). Note that the CAMLST macro 
instruction sets these bits to zero, corresponding to case zero. 


Non-locate requests are recognized by Controller II when the case bits are set to 
0, 1, 3, and 6. The parameter list passed to the controller determines which 
catalog the request will be routed to; however, duplicate entry checks are made 
in the opposite catalog on all catalog-type requests. 


Operation I continues by initializing a work area named WORKAREA. The data 
set SYSCTLG is opened by constructing a data control block (DCB) and a data 
extent block (DEB), which are shown as intermediate results in Figure 7. The 
BLDL macro instruction uses the DCB and DEB to read blocks of the catalog. The 
components of the name are isolated, and the high-level name is used as the 
search parameter of BLDL. BLDL begins by reading the block that contains the 
entry for the high-level name. 


If the entry that is found is a CVOL pointer entry, the current CVO is closed and 
the CVOL identified by the pointer is opened. The process repeats until the 
appropriate CVOL is open. 


If the entry points to a lower level of the index structure, BLDL is called with the 
next component of the data set name as a search parameter. This process is 
repeated until the volume list is read (for locate functions), or the last valid level 
of the structure is found (for non-locate functions). 


Insert A in Figure 7 shows how the blocks of the catalog are chained together 
and how keys are used in this chaining process. The blocks are visualized in this 
insert as several contiguous blocks in the catalog, with block addresses ascending 
from left to right. The last entry of any catalog block is the index link entry 
(ILE), which is used to chain one block of an index to the next block in the same 
index. When two blocks are chained together but are not contiguous, as in the 
case of the first and fourth blocks in the insert for index A, the first block of the 
pair has a key equal to X'FFFFFFFFFFFFFFFF’. BLDL issues a “search key 
high-or-equal”’ operation to the direct access device. When searching 
non-contiguous blocks, the high value of the key causes each block to be read 
and scanned for the requested name. 


However, when two blocks are chained together and are contiguous, as is the 
case with index B with the second and third blocks of the insert, the first block 
of the pair has a key equal to the name in the next-to-last entry of that block. 
The ‘search key high-or-equal”’ operation stops on such a block only if the 
requested name could be in it; otherwise, the search continues with the next 
contiguous block. 


Available blocks (that is, blocks that are unused) have a key equal to 
X‘0000000000000000°. Thus an available block of the catalog can be found by 
searching for a zero key. 
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¢ CAMLST is described on page 67 

¢ SYSCTLG entries are described beginning on page 61 

e Figure 7 is found on page 20 

¢ Figure 8 is found on page 22 

¢ Figure 9 is found on page 23 

¢ CVT, TCB, and SVRB are described in OS Control Blocks , GC28-6628. 
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Notes: 

e CAMLST is described on page 67 

e WORKAREA is described on page 68 

e BLDLAREA is described on page 72 

« CVT, TCB, SVRB, VTOC, DCB, and 
DEB are described in OS/VS System 
Data Areas, SY28-0605. 

« Figure 6 is found on page 19 
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e Operation I uses modules: 


IGCOOO2F pages 32 and 34 


IGGOCLCO page 40 
IGGOCLCI page 42 
IGGOCLC2 page 44 
IGGOCLC3 page 46 


e Opening a CVOL uses modules: 


IGC0002H page 56 
IGGOCLF2 page 58 


The key of an unused 
block is a binary zero. 





Operation II, Setup 


Operation Ill, Write 


Figure 8 illustrates the setup operation. Input to this operation includes the name 
of an entry to be added or deleted from the catalog. This might be the simple 
name of a data set to be cataloged or removed from the catalog, or it might be 
an index name for a level to be created or deleted. Other information needed to 
build a new entry might be passed, depending on the request. The catalog block 
to which the change is to be made remains in a buffer from Operation I. 


The setup process consists of either naming an entry to be deleted or 
constructing a new entry, then copying the catalog block one entry at a time 
from an input buffer to an output buffer. The new entry is merged into collating 
sequence with the old entries, or the named entry is bypassed, depending on the 
request. 


Adding or deleting entries causes the following entries in the index to be 
displaced. For example, adding to a full block can result in an ‘‘overflow”’ of 
entries. These overflow entries must be added to the next block in the index 
chain. The effect of a change can thus ripple down the index chain. Similarly, a 
deletion can result in rippling in the other direction. 


Figure 9 illustrates the write operation. Input to the operation is an updated 
catalog block and a relative track address to which this block is to be rewritten 
into SYSCTLG. Rippling can cause several blocks to be rewritten. Finally, the 
block containing the index control entry (ICE) and the volume index control 
entry (VICE) are updated and rewritten to reflect the changes made to the 
catalog. Output is the updated catalog. 


The insert to Figure 9 shows how the CATBX function is performed. In this case, 
the index levels to which a data set name is to be added do not exist; these index 
levels must also be created. This is done from the bottom up. 


Step 1 shows the new data set pointer entry (DSPE) ready to be added to the 
catalog. A new index block is constructed and this DSPE is inserted into it. The 
newly constructed index block is written to the first available space in SYSCTLG, 
and the relative track address of that block is saved for step 2. The catalog is 
searched for another available space. 


In step 2, a new index pointer entry (IPE) is created for the index block written 

in step 1, using the relative track address from step 1. If the next higher level of 
the index structure is also missing, another index block is created and written to 

SYSCTLG. 


This process is repeated until a level is finally reached that does exist (step 3). 
An IPE is constructed for the highest new index and is added to the existing 
level. 


For example, if the data set name A.B.C.DATASET were added to the catalog 
when none of the index levels A, B, or C exist, then step 1 would build index 
level C with a DSPE for A.B.C.DATASET in it. Step 2 would first build index level 
B with an IPE for C in it, and then index level A with an IPE for B in it. Finally, 
step 3 would insert an IPE for A into the volume index. 
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e SYSCTLG entries are described beginning on page 61 


« BLDLAREA is described on page 72 
e Figure 6 ts found on page 19 


e Operation II uses modules: 


IGGOCLC3 page 46 
IGGOCLC4 page 48 
IGGOCLCS page 50 
IGGOCLC6 page 52 
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Step 1 Since the lowest-level index does not exist, 
a new block is created and the data set name 
is cataloged into that block. The new block 
is written into the first available space in 
SYSCTLG, and its address saved for step 2. 


Notes: 
« Figure 6 ts found on page 19. 


Process 


See Figure 6 — to relate this 
process to overall Method 
of Operation. 


Re-write block of SYSCTLG. 


Changes to this block may ripple 
to following blocks of index 
chain; that is, a change to 
following blocks might now be 
setup (repeat Operation II). 
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Step 2 An index pointer entry is built for ‘the block 
created in step 1 and inserted into the next higher 
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« SYSCTLG entries are described beginning on page 61. 


¢« Operation III uses modules: 


IGGOCLC3 page 46 
IGGOCLCS page 50 
IGGOCLC6 page 52 
IGGOCLC7 page 54 


Figure 9. Operation I1I—Write, with CATBX Detail 
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This chapter discusses the implementation of the catalog management routines, 
showing how the actual modules fit together. 


The final authority of any program is the assembly or compilation listing. These 
module discussions complement the assembly-listing comments, and assume that 
the listings are at hand. You should have them available for any in-depth 
analysis. 


The three operations described in the previous chapter, ‘““Method of Operation,” 

form a conceptual image of catalog management. In reality, the broad operations 
of read, setup, and write merge together somewhat when packaged into modules. 
Still, the concept is useful, and it is continued in this chapter. 


There are 11 or 13 modules in catalog management, depending on whether 
Controller I or Controller II is present. Eight modules and the controller form 
three phases, and two of the modules provide auxiliary services used by any 
phase. 


Phase I equates to the read operation. It performs locate functions and the 
corresponding part of non-locate functions. Phase I consists of: 


e Controller I or II, which routes the catalog management request to the 
appropriate routines. 


| © IGGOCLCO, Initialization, which initializes work areas and opens the CVOL. 


e IGGOCLC1, Relative GDG and Alias, which resolves aliases and relative GDG 
numbers. 


e IGGOCLC2, Locate, which searches the lower levels of the index structure. 


Phase II begins the setup operation. It checks the validity of the requests against 
the existing entries in SYSCTLG, and it builds new entries to be added or it 
names entries to be deleted. Phase II consists of: 


¢ IGGOCLC3, Update Initialization and Entry Building, which begins the update 
process by building new index blocks and routing the request as needed. 


e IGGOCLC4, Entry Building, which builds data set pointer entries to add to the 
last valid level of the index. 


Phase III completes the setup operation and performs the write operation. It 
merges entries into SYSCTLG blocks, deletes entries from blocks, and does most 
of the writing that is needed. Phase III consists of: 


e IGGOCLCS, First Load of Update, which frees index blocks, frees volume 
control blocks (VCBs), and writes new VCBs. 


e IGGOCLC6, Second Load of Update, which updates blocks, writes updated 
blocks to SYSCTLG, and ripples the change as needed to the last block of the 
updated chain. 


e IGGOCLC7, Third Load of Update and Error Handling, which writes the last 
updated block, updates the control entries, returns control to IGC0002F, and 
also handles error conditions. 
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The two service modules are: 


e IGC0002H, SYSCTLG Open/Extend, which opens the SYSCTLG data set or gets 
the next extent of that data set, when needed. 


e IGGOCLF2, SYSCTLG and BPAM Directory Formatter, which formats a new 
catalog and any new extents of a catalog. | 


Each of these modules operates in a transient area. IGC0002F, the entry point for 
catalog management, is invoked by a caller with an SVC 26; control is passed to 
the other eight modules of the phases via an XCTL macro instruction. IGC0002H, 
one of the service modules, is invoked via an SVC 28; it passes control to 
IGGOCLF2 via an XCTL macro instruction. 


Figure 10 shows the organization of modules with relation to the phase structure 
and illustrates the overall flow of control from one module to another. 


One-Catalog Environment 


1GCOO002F — 


e Route requests to OS/VS or 
VSAM Catalog Management. 





Two-Catalog Environment 


U 


SVC 26 


iGCOQO002F— 
e Route requests to OS/VS 
Catalog Management 


IGGOCLCA- 


@ Resume processing of 
OS/VS requests. 
@ Reformat VSAM output to OS/VS. 


IGGOCLCB— 


@ Resume processing of VSAM 
requests. 
e Reformat OS/VS output to VSAM. 





Figure 10. (Part 1 of 2) Overall Program Organization 
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Figure 10. (Part 2 of 2) Overall Program Organization 


An SVC 26 invokes the catalog management routines; control is then passed to 
IGC0002F, the catalog controller. The path that occurs through the remaining 
modules depends on both the particular function that is requested and the entries 
that are found in the catalog. 
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Each block in Figure 10 represents a module of the catalog management routines 
and contains a brief description of the functions that it performs. Each path is 
identified by the function/condition that it represents. 


For example, follow the path for a BLDX function (request to create an index 
level) on a VS catalog. Assume that part of the index structure already exists; 
that is, this request extends an existing index structure. 


Specifically, this is what each module does to accomplish the BLDX request: 


e Entry to catalog management is at IGC0002F, which routes the request to 
IGGOCLCO. 


e IGGOCLCO initializes work areas, opens the CVOL, and locates the high-level 
name of the index structure. The arrow labeled ‘Other’ is the exit path for 
this example. 


e IGGOCLC2 locates the remaining levels of the existing index structure, to find 
the last valid level. The new index is to be added to that level. 


e BLDX is a non-locate function, so control passes to IGGOCLC3. This module 
reads the control entries (VICE and ICE), constructs an index pointer entry 
(IPE), and routes the request via the arrow labeled ‘‘Other.”’ 


¢« IGGOCLC6 inserts the new IPE into the index block left by IGGOCLC2. 
IGGOCLC6 writes the updated block to SYSCTLG, and ripples the effect of the 
change down the index chain, if necessary. The last block of the chain is left 
in the input/output buffers, but it is not written to SYSCTLG. 


e IGGOCLC7 writes the last block of the updated index chain, then reads, 
updates, and rewrites blocks containing the index control entry (ICE) and 
volume index control entry (VICE). Resources are released and control passes 
back to IGC0002F for return to the caller. 


Traces such as the one just discussed are illustrated in the chapter “‘Diagnostic 
Aids” as an aid in identifying the modules involved in any particular situation. 


All of the VS catalog management modules are re-entrant. They use a common 
work space, initialized by IGGOCLCO and called WORKAREA. (WORKAREA is 
described on page 68.) 


Macros and Services Used 
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A small set of macros and services is used throughout the catalog management 
routines. The prologue commentary for each module lists the specific ones used 
in that module; the complete set is: 


« BLDL, the routine used by Phase I to read blocks of SYSCTLG, which is 
formatted like a partitioned data set (PDS) directory. It is accessed through 
entry point IECPBLDL, whose address is found in field CVTPBLDL of the 
Communication Vector Table (CVT). In Phase I catalog management routines, 
this routine is used in a closed subroutine labeled ““CALLBLDL”’. 


e IECPCNVT, a routine used to convert relative track addresses to absolute 
addresses. It is accessed through entry point IECPCNVT, whose address is 
found in field CVTPCNVT of the CVT. In the catalog management routines, 
this routine is used in the closed subroutine labeled ““TOABSL”’. 


e IECPRLTV, a routine used to convert absolute track addresses to relative 
addresses. It is accessed through entry point IECPRLTV, whose address is 
found in field CVTPRLTV of the CVT. In the catalog management routines, this 
routine is used in a closed subroutine labeled ‘““TORLTV’’. 


« ENQ, a macro instruction used to control three resources: high-level name, 
volume index, and volume index control entry (VICE). 
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Character Dependency 


Resource Enqueuing 


Register Usage 


e DEQ, a macro instruction used to release resources obtained by the ENQ 
macro. 


e EXCP, a macro instruction used for input/output operations in Phase II and 
Phase III modules. In the catalog management routines, this instruction is used 
in a closed subroutine labeled ‘‘10” 


e EXIT, a SVC instruction used to return to the caller. 


e XCTL, a macro instruction used to pass control from one catalog management 
module to another. 


¢ GETMAIN, a macro instruction used to allocate main storage. It is used by 
catalog management to obtain work areas and input/output buffers. 


« WAIT, a macro instruction that allows an input/output operation to complete 
before continuing processing. 


e FREEMAIN, a macro instruction used to release main storage used for work 
areas by catalog management. 


* SCRATCH, a macro instruction used to delete a data set. 


* DSECT macros IEFUCBOB and CVT, which describe system control blocks. 


The modules of catalog management require that the character set used at 
execution time be equivalent to that used at assembly time. The IBM-supplied 
version of catalog management assumes EBCDIC character representations. If a 
different character set is to be used during execution, the modules must be 
re-assembled. The instructions involved in this dependency are identified by label 
in the prologue commentary of each module. 


Figure 11 shows when the resources of catalog management are enqueued in 
relation to the modules. Three resources are used: high-level name, volume 
index, and volume index control entry (VICE). To prevent an interlock between 
two callers, the high-level name is always enqueued first, the volume index is 
enqueued second, and the VICE is enqueued last. 


The conditions of enqueuing are determined from the request. If the volume 
index is to be modified, then the volume index must be enqueued exclusively. 
Otherwise, it can be shared. If a locate function is requested, then the high-level 
name can be shared. If a non-locate function is requested, the high-level name is 
enqueued exclusively to protect all lower-level indexes under it. 


The major name for enqueuing is always “‘SYSCTLG’’. The minor name is the 
high-level name with the UCB address appended to it, ““SYSCTLG”’ with the UCB 
address appended to it, or zeros with the UCB address appended to it. 


With the exception of 1GC0002H and IGGOCLF2, the catalog-management modules 
use a common set of registers. Module IGGOCLCO initializes these registers, and 
their contents remain throughout. Contents of registers not described are 
considered destroyed. 


Registers 


4 Base register for the module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
14 Linkage register for BAL instructions 
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Figure 11. Resource Enqueuing 
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Module Descriptions sila alec : 
Each of the modules of catalog management is described in this section. The 
flowcharts are organized into two parts. Supporting text for the module appears 
beside each part. 


Error-condition tests are not shown on the flowcharts. An error condition results 
in a branch to label ERRxx, where xx is the appropriate error code. There the 
error exception code is set and an XCTL to IGGOCLC7 occurs. The labels on the 
flowchart are those used in the assembly listing. 
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IGCOOO2F: Controller | 


Note: This controller exists if 
VSAM=EXCLUDE was specified in the 
CTRLPRDG macro at system generation. 


IGC0002F is the entry point for the catalog 
management routines, which are invoked by 
an SVC 26. IGC0002F is also entered from the 
following modules via XCTL, for return to the 
caller: 


¢ IGGOCLC1 
e IGGOCLC2 
¢ IGGOCLC7 


Registers 
On Entry via SVC 26: 


1 Address of caller’s parameter list 
3 Address of CVT 
4 Address of SVRB 


Functions 


The module routes a request for catalog 
management to IGGOCLCO without change 
when the caller is not a VSAM request. When 
the request is a VSAM request, IGC0002F: 


1. Translates the VSAM parameter list into 
CAMLST form and invokes normai 
catalog management routines (XCTL to 
IGGOCLCO). 


2. Translates the results of the catalog 
search to VSAM format. 


Internal Subroutines 


STRTCNTL handles the initial entry into 
1GC0002F by determining what functions are 
requested. 


RESMCNTL handles subsequent re-entries of 
IGC0002F by determining if further functions 
are needed to satisfy the request. 


FUNCT6 is used when the parameter list is 
already in the form of a CAMLST. 


FUNCT7 is used when the parameter list is in 
VSAM form. 


RESUME7 passes catalog information back to 
a VSAM caller, and controls further catalog 
searches when such is required. 
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OSPL translates a VSAM parameter list into a A2 A 
CAMLST FUNCT6 FUNCT7 


AMORD translates the results of a single 
catalog search into VSAM format. 










CNTL2CAT handles cases when there are more ee Translate VSAM 
‘ ‘ ROUTE = XCTL rameter list 
than 20 volumes in the volume list. point to CAMLST © CAMLST. ( 


AMORC converts a catalog management 
exception code to VSAM format. 


FREERTN frees the work area that was 3 


1 2 
obtained for a VSAM locate request. (| resume7 Return point to CAMLST 


Exits 





Control passes via an XCTL macro instruction 


D2 
to IGGOCLCO. 
Convert to VSAM 
Error return return code 


(rtn AMORC) 


D3 
Return 






Error Conditions 
Code Reason 


4 CVOL not mounted or does not 
contain SYSCTLG. 





20 Syntax error in data set name. 
24 Permanent input/output error. 


28 Bad relative track address for 
SYSCTLG. 


More blks 
of vol-list 






32 Bad address for caller’s area. 


F2 
ROUTE = XCTL 
(rtn CNTL2CAT} 


2 


FREEMAIN for 
WORKAREA 


36 Data set not found. 






40 Output area provided by caller is too 






ROUTE = EXIT 


small. 
48 Requested function is not supported. 
References = | 

Page Return 

Item number 
IGGOCLCO 40 
CAMLSTD 67 
Method of Operation Figure 7 20 


CVT, TCB, SVRB, DCB, DEB, and UCB are 
described in OS/VS! System Data Areas, 
SY28-0605. 
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IGCOOO2F: Controller Il 





at system generation. 


IGC0002F is the entry point for the catalog 
management routines, which are invoked by 
an SVC 26. IGC0002F is also entered from the 
following modules: 


¢ IGGOCLC1 
¢ IGGOCLC2 
¢ IGGOCLC7 
e IGGOCLC9 


Registers 
On Entry via SVC 26: 


1 Address of caller’s parameter list 
3 Address of CVT 

4 Address of TCB 

5 Address of SVRB 


On Re-entry via XCTL: 


1 Negative number 
2 Return code 
12 Address of Controller’s work area 


Functions 


This module determines the type of request 
for catalog management and routes the 
request to the OS/VS (IGGOCLCO) or the 
VSAM (IGGOCLA1) catalog. 


This module is also the entry point for all 
returns from either catalog. It determines the 
original type of request and routes to 
IGGOCLCA (original OS/VS requests) or 
IGGOCLCB (original VSAM requests), if 
additional processing is necessary. 


The calling of initial and resume functions is 
based on the following: 


2 
XCTL from other catalog 
management routines 


# of Start 
Crigs Parm Crlg 
Case to Search List Search 

0 2 OS/VS VSAM 
1 2 VSAM VSAM 
2 | OS/VS VSAM 
3 1 VSAM VSAM 
4 2 OS/VS OS/VS 
6 1 OS/VS OS/VS 


| Note: This module exists unless you specify a e a2 
is is oe Enter Catalo Type of Init GETMAIN for 
VSAM=EXCLUDE” in the CTRLPROG macro ve enti fgest >>] | local save 





6 for initial entry 


B3 


Save 
information 
about request 


2 3 
a STRTCNTL 
Pee a Defexmene 

func on Peegnae yen" tae functl qn to 


| focmed” 


eerie for 
ROUTE=XCTL roca oii 


E3 
Restare Restore 
tht, | registers 
about tht, | 


XCTL (SVC 7) to Exit (SVC 3) to 
ctlg mgmt ( caller 
| STRTCNTL 
Function 0 
Case 0 ; 
non-locate | Function 6 


locate Function | 











non-locate | Function 3 







locate Function 2 


non-locate 












locate Function 3 


non-locate 


|non-locate 






Function 3 


Function 4 






Case 4 














locate Furtction 6 





Case 6 









non-locate | Function 6 


None of the above 


—s 
Return 


The case is determined by the decimal 
equivalent of the last three bits in CAMOPTN3 
of the CAMLST (see page 67). Note that the 
CAMLST macro instruction sets these bits to 
zero, corresponding to case zero. 
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Internal Subroutines 


STRTCNTL handles the initial entry into 
IGC0002F to determine which function is 
required. 


RESMCNTL handles subsequent entries into 
I1GC0002F and routes to the appropriate 
module for addition processing. 


FUNCTO routes OS/VS requests to the VSAM 
catalog for a two-catalog search. 


FUNCT2 routes directly to the VSAM catalog. 


FUNCT3 routes VSAM DEFINE requests to the 
OS/VS catalog for a duplication check before 
any action is taken. All other requests go 
directly to the VSAM catalog. 


FUNCT4 routes directly to the OS/VS catalog. 


FUNCT6 routes OS/VS CATLG requests to the 
VSAM Catalog for a duplication check before 
any action is taken. 


AMOPL translates a CAMLST into a VSAM 
parameter list. 


OSPL translates a VSAM parameter list into a 
CAMLST. 


For a description of the VSAM parameter list, 
see the chapter “‘Data Areas” in OS/VS VSAM 
Logic, SY26-3805. 


Exits 


Control passes via an XCTL macro instructiqn 
to: 


e IGGOCLCA 

e IGGOCLCB 

e IGGOCLCO 

e IGGOCLAI 
References 

Page 

Item number 
CAMLSTD 67 
IGGOCLCA 36 
IGGOCLCB 38 
IGGOCLCO 40 
Method of Operation Figure 7 20 


CVT, TCB, SVRB, DCB, DEB and UCB are 
described in OS/VS1 System Data Areas, 
SY28-0605. 
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IGGOCLCA: Resume Processing of OS/VS Requests 


IGGOCLCA is the entry point. Control comes 
from: 


e IGC0002F after determining which 
catalog was originally requested. 


Registers 
12 Address of @DATD 


Functions 


This module determines the status of the 
original request. It routes control to either 
catalog if additional processing is required and 
performs whatever conversions or translations 
are mecessary. 


RESMCNTL determines which resume function 
is required. 


RESUME 1 continues the processing of 
FUNCTION if the entry was not found in the 
VSAM catalog. If the entry was found, 
RESUME] performs the necessary 
OS/VS-to-VSAM conversions. 


RESUME? continues the processing of 
FUNCTION3 if the entry was not found in the 
OS/VS catalog. If the entry was found, 
RESUME3 translates the return code. 


OSPL translates a VSAM parameter list into a 
CAMLST. 


H 1 


Set ue XCTL for| NO ec Request 
OS/VS Catalog Complete 


K1 
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AMORD formats OS/VS information into the 


VSAM format. 
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IGGOCLCB: Resume Processing of VSAM Requests 


IGGOCLCB is the entry point. Control comes a3 AS 
from: IGGOCLCB )——_—_+ ROUTE=EXIT RESMCNTL 


e IGC0002F after determining which 





catalog was originally requested. 
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RESUMBE3 continues the processing of (Cfesine >) 
FUNCTION3 if the entry was not found in the 
OS/VS catalog. If the entry was found, 
RESUMB3 translates the return code. 


OSPL translates a VSAM parameter list into a 


B 
CAMLST. , 
AMORD formats OS/VS information into the 


VSAM format. 







AMORC translates OS/VS return codes into 


Cc 
VSAM return codes. SAM Define 
Request 
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YES 
than 20 volumes in the volume list. 
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IGGOCLCO: Initialization 


Note: This module is named IGC0002F in 
OS/VS1 Release 1. 


IGGOCLCO is the entry point. Control comes 
from IGC0002F. 


Registers 
On Entry: 


1 Address of caller’s parameter list 
(CAMLST) 

3. Address of CVT 

4 Address of TCB 

5 Address of SVRB 


On Exit: 


2 Address of UCB 

Base register for this module 

Pointer to SVRB extension 

Base register for WORKAREA DSECT 
Base register for CAMLSTD DSECT 
Address of CVT 

12 Linkage register for BAL instructions 
13. Base register for BLDLAREA 

14 Linkage register for BAL instructions 


Onn & 


Functions 


WORKAREA is the common workspace and 
communications area for all catalog 
management modules. When a locate 
function is requested, WORKAREA is built 
over the caller’s 265-byte area, and a second 
area (called BLDLAREA) is obtained by 
GETMAIN. BLDLAREA is used with the 
routine BLDL. 


When a non-locate function is requested, a 
larger area is obtained by GETMAIN for 
WORKAREA. Part of this area is used for 
BLDLAREA during execution of modules 
IGGOCLCO, IGGOCLC1, and IGGOCLC2. This 
portion of WORKAREA is redefined for use as 
input/output buffers thereafter. 


The first 256 bytes of WORKAREA are set to 
zero, which initializes all switches and flags. 
Supervisor addresses and the data set name 
go into WORKAREA, and the data set name is 
decomposed into its components. BLDLAREA 
is initialized for use as input/output buffers. 


The UCB table is searched for device 
information about the given CVOL. GETMAIN 
is used to allocate space for a DCB and a 
DEB, and IGC0002H is used to open the CVOL 
(via an SVC 28). 
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MOVEHIL 
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Note: The OPEN macro instruction is not 
used to open a CVOL. IGC0002H constructs a 
modified DCB/DEB for use by catalog 
management; IGC0002H is described on page 
56. No CLOSE macro is issued to close a 
CVOL. FREEMAIN simply releases the main 
storage that is used for the modified 
DCB/DEB. 


The first component of the data set name is 
used as the search parameter for BLDL. 
Searching begins with the first block of 
SYSCTLG. If BLDL returns a CVOL pointer 
entry (and the request is not LNKX or DRPX), 
the current CVOL is closed and control goes 
back to label UCBSRCH (block A1). 


Internal Subroutines 


None. 


Exits 


Control passes via an XCTL macro instruction 
to: 


e IGGOCLC1 if requested function is BLDA or 
LNKX, or if the high-level name is an alias. 

e IGGOCLC7 for an error condition. 

e IGGOCLC2 otherwise. 


Control passes via an SVC 28 to IGC0002H to 
open the catalog, and returns to this module. 
Error Conditions 


Code Reason 


4 CVOL not mounted or does not 
contain SYSCTLG. 
20 Syntax error in data set name. 
24 Permanent input/output error. 
28 Bad relative track address for 
SYSCTLG. 

32 Bad address for caller’s area. 
References 

Page 
Item number 
IGC0002F 32 and 34 
IGGOCLCI1 42 
IGGOCLC2 44 
IGGOCLC7 54 
1GC0002H 56 
SYSCTLG Entries 61 
CAMLSTD 67 
WORKAREA 68 
BLDLAREA 72 
Method of Operation Figure 7 20 


CVT, TCB, SVRB, DCB, DEB, and UCB are 
described in OS/VS!I System Data Areas, 
SY28-0605. 
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IGGOCLC1: Relative GDG and Alias 


IGGOCLC1 is the entry point. Control comes 
from: 


e IGGOCLCO when the requested function is 
either BLDA or LNKX, locate-by-block, or 
when an alias is found (except with a 
DLTA request). 


e IGGOCLC2 when a relative GDG number is 
found in the data set name. 


Registers 


4 Base register for this module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
13. Base register for BLDLAREA 
14 Linkage register for BAL instructions 


Functions 


When locate-by-block is requested, the block 
is read and returned to the caller. 


When control comes from IGGOCLC2, control 
goes to label RELGDG for relative GDG 
processing. 


If the requested function is BLDA or LNKX, 
the appropriate entry is constructed and 
control passes to IGGOCLC2 for routine to the 
update modules. 


When an alias is discovered, the fully 
qualified name is reconstructed in the caller’s 
name area, using the true name. The name 
table is then updated to reflect the change 
and the high-level name is re-enqueued. 


Control comes from IGGOCLC2 when a 
relative GDG number is discovered in the data 
set name. This module determines the 
absolute GDG name for the data set. If the 
request is a locate function, either the volume 
list for the data set or a new absolute GDG 
name is returned to the caller. Otherwise, an 
error condition exists and IGGOCLC7 is 
invoked. 


The generation number in absolute GDG 
names is complemented before the names are 
added to the generation index. Therefore, the 
most recent entry (the highest generation 
number) is the first entry in the index, the 
second most recent entry is the second entry 
in the index, etc. 


When the relative GDG number is negative or 
zero, an absolute GDG name from the 
generation index is returned to the caller 
along with the corresponding volume list. 
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Zero corresponds to the first entry, -1 
corresponds to the second entry, etc. 


When the relative GDG number is positive, a 
new absolute GDG name is created and 
returned to the caller. If the generation index 
is empty, this name is Goo0OnVooO (where n is 
the relative number). If the generation index 
is not empty, the relative GDG number is 
added to the generation number of the first 
entry to create the new absolute GDG name. 


Internal Subroutines 

CALLBLDL calls BLDL routine via entry point 
IECPBLDL. 

Exits 

Control passes via an XCTL macro instruction 
to: 

e IGC0002F after relative GDG processing. 

e IGGOCLC7 for error conditions. 


e IGGOCLC2 otherwise. 


Error Conditions 
Code Reason 


8 Name not found for locate function, 
or existing structure inconsistent with 
request for non-locate function. 


20 Syntax error in data set name. 
28 Permanent I/O error. 
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IGGOCLC2: Locate 


IGGOCLC2 is the entry point. Control comes 
from: 


e IGGOCLC! after resolying an alias or 
constructing and entry for BLDA or LNKX 
request. 


e IGGOCLCO otherwise. 


Registers 


4 Base register for this module 
6 Base register for WORKAREA DSECT 
8 Base register for CAMLSTD DSECT 
12 Linkage register for BALR instructions 
13. Base register for BLDLAREA 
14 Linkage register for BALR instructions 


Functions 


This module completes the locate functions, 
or finds the last valid index level for a 
non-locate function. BLDL is used to search 
index levels successively. At each index level, 
one component of the data set name is used. 
When locate-by-name is requested, BLDL is 
used with each component of the data set 
name as the search parameter. When BLDL 
returns an index pointer entry (IPE), use it to 
determine the track address for the next 
search. The search by BLDL continues with 
the next component of the name. 


When BLDL returns a data set pointer entry 
(DSPE) or volume control block pointer entry 
(VCBPE), the corresponding volume list is 
returned to the caller. 


When the request is for a non-locate function 
and BLDL fails to find the next level, the 
update process is initiated. 


The last valid level of the existing index 
structure is saved to use while updating. 


IGGOCLC2 contains skeletal channel programs 
that are used by the non-locate modules. 
These CCW chains are moved to BLDLAREA. 
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Internal Subroutines 


UCATDX maintains a TTR trail of blocks that 
can be deleted. 


CALLBLDL calls BLDL to search for one 
name. 


TORLTV converts an absolute address to a 
relative track address. 


NEXTLVL gets the component of the data set 
name in order to search for the next level. 
Exits 


When the request is a locate function, control 
returns to: 


e 1GC0002F along with the volume list for the 
data set name (via XCTL SVC instruction). 


« IGGOCLC!1 for relative GDG number. 


When the request is for a non-locate function, 
control passes to: 


e IGGOCLC7 for an error condition. 


« IGGOCLC3 otherwise. 


Error Conditions 
Code Reason 


8 Name not found for locate request or 
existing structure inconsistent with 
non-locate request. 


12 Last entry found was an IPE, CVPE, 

or alias with locate request. 
16 Non-existent index levels specified. 
20 Syntax error in data set name. 
28 Permanent !/O error. 
References 

Page 

Item number 
1GC0002F 32 and 34 
IGGOCLCO 40 
IGGOCLC] 42 
IGGOCLC3 46 
IGGOCLC7 54 
WORKAREA 68 
BLDLAREA 72 
Method of Operation Figure 7 20 


SoO900 
amnOoe 
Ne at at DD 





CLCIJPREP 
A} Ad 






Save TTR for Save ICE iff it 
last block read|-—————> wa>. ee Lead 
in 









Bi 
Save last level 
nan 4 oo 


R 


fiunetion 


“est 










function virtn 
NEX 





Request 
UCATDX 
function 






Relocate CCWs 
into WORKAREA 
for vse 

later modules 






Extend ment 
ares and CC RPS device 
chain for RPS 






IGGOCLC 3 


UCATDX 


1 
( Pointing to ) 
block a 
workarea 







not delete Ist or 2nd level Block 
Block with more than | encey:, 
irst block in index chal 





Deletable 
block piock to to "upsate 


WRITE 





2 
SD Return 


1 
Save TTR fo 
Ist deletable 
block in 
DELTT 






Program Organization 45 


IGGOCLC3: Update Initialization and Entry Building 


IGGOCLC3 is the entry point. Control comes 
from: 


¢ IGGOCLC4 after constructing a DSPE for a 
CATBX request. 

e IGGOCLCS5 after writing a volume control 
block and constructing a VCBPE for a 
CATBX function. 

e IGGOCLC2 otherwise. 


Registers 


4 Base register for this module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
14 Linkage register for BAL instructions 


Functions 


When entry is from IGGOCLC4 or IGGOCLCS, 
index levels for a CATBX request must be 
built. Control goes to label CATBX on the 
next subchart. 


When control comes from IGGOCLC2, the 
index control entry (ICE), if not already 
present, and volume index control entry 
(VICE) are read. The request is checked 
against available space in SYSCTLG to ensure 
that there is enough space to make the 
required changes. 


This module constructs new index levels for a 
BLDX function and constructs an index 
pointer entry for the new level to be added to 
the existing structure. When the requested 
function is DRPX or DLTA, the entry to be 
removed is named and IGGOCLC6 will delete 
it. 


When CATBxX is requested, IGGOCLC4 is called 
to construct the DSPE. Control returns to 
IGGOCLC3, where the required index levels are 
built and written into SYSCTLG. Each level 
results in an index pointer entry (IPE) that 
must be added to the next higher level. When 
an existing level is reached, contro! passes to 
IGGOCLC6. 


IGGOCLC3 routes the update request to the 
modules that perform the appropriate 
function. 


Internal Subroutines 


MOVELVL gets the component of the data set 
name for the current index level from the 
name table. 


WRTSRCH writes a new block to SYSCTLG 
and searches for another available block. 
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KEYICE constructs a new index block, with its 
ICE and key. 


TOABSL converts a relative track address to 
an absolute track address. 


TORLTV converts an absolute track address to 
a relative track address. 


1O performs EXCP input/output. This 
subroutine invokes IGC0002H if a new extent 
of SYSCTLG Is required. 


Exits 


Control passes via an XCTL macro instruction 

to: 

e IGGOCLC4 when the requested function is 
CATBX, CAT, RECAT, or UNCAT. 


e IGGOCLCS5 when blocks of SYSCTLG need 
to be freed, or when new blocks have been 
written, but the requested process has been 
aborted. 


e IGGOCLC7 for error conditions. 
e IGGOCLC6 otherwise. 


Control passes via an SVC 28 to 1GC0002H 
when a new extent of SYSCTLG is required or 
when SYSCTLG must be re-opened, and 
returns to this module. 


Error Conditions 


Code Reason 


8 Existing structure is inconsistent with 
the requested function. 

12 Attempt to delete a non-empty index 
level. 

20 Not enough space available in 
SYSCTLG to perform the requested 
function. 

28 Permanent I/O error. 
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IGGOCLC4: Entry Building 


IGGOCLC4 is the entry point. Control comes 
from IGGOCLC3 when the requested function 
is CAT, CATBX, RECAT, or UNCAT. 


Registers 

4 Base register for this module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
14 Linkage register for BAL instructions 


Functions 


If the requested function is RECAT or UNCAT, 
control passes to label ALTERTN. If the 
request is for CAT or CATBX, control passes 
to label CATRTN. 


This module constructs a new DSPE or 

VCBPE. When there are more than five 
volumes in the volume list, IGGOCLCS is 
invoked to write volume control blocks. 


If the data set name is not for a generation 
data group, control passes to label 
CULMINAT. Part two of the flowchart deals 
with cataloging functions to a generation 
index. The new member of a GDG is checked 
against existing members to see if this is a 
new version of an existing member. 


If the maximum number of entries that a 
generation index can hold is exceeded with 
this addition, the options for GDG are 
processed. 


If EMPTY was specified, IGGOCLCS will 
remove all entries from the generation index 
before adding the new entry. Otherwise, 
IGGOCLCS will remove only the oldest entry 
before adding the new entry. This module 
(IGGOCLC4) flags what is to be done. 


If DELETE was specified, then this module 
(IGGOCLC4) issues the SCRATCH macro 
instruction on every data set name that will 
be removed by IGGOCLCS. If DELETE was 
not specified, nothing is scratched. 


The RECAT and UNCAT functions are 
processed by naming the old entry. IGGOCLC6 
will delete the old entry when it gets control. 
For RECAT, a new entry is also constructed. 
IGGOCLC6 will add this new entry to the 
catalog. 


Internal Subroutines 


TOABSL converts an absolute track address to 
a relative track address. 
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IO performs EXCP input/output operations. 


GET reads a block from SYSCTLG into the 
input buffer of BLDLAREA. 


SETUP points to the first and last entry in an 
index block. 


INCR bumps the pointer to the next entry in 
an index block. 


BLDENTRY constructs a data set pointer entry 
(DSPE) or a volume control block pointer 
entry (VCBPE). 


SCRATCH performs a SCRATCH macro 
instruction for one data set and its VCBs. 


Exits 


Control is passed via an XCTL macro 
instruction to: 


¢ IGGOCLC3 when CATBX is being 
performed. 

e IGGOCLCS when auxiliary reading or 
writing is required: 


— Volume control blocks (VCBs) need to 
be written. 

— VCBs or index blocks need to be freed. 

— The DELETE option of a GDG needs to 
be performed. 

— Updated GDG index blocks need to be 
rewritten. 


e {JGGOCLC7 for error conditions. 
« IGGOCLC6 otherwise. 
Error Conditions 


Code Reason 


8 Existing structure is inconsistent with 
requested function. 
16 Non-existent index level required. 
24 Improperly named GDG data set, or 


GDG data set to be added is older 
than existing GDG data sets. 


28 Permanent |/O error. 
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IGGOCLCS: First Load of Update 


IGGOCLCS is the entry point. Control comes 
from IGGOCLC3 or IGGOCLC4 when blocks of 
the catalog need to be written or freed. 


Registers 

4 Base register for this module 

6 Base register for WORKAREA DSECT 

8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
14 Linkage register for BAL instructions 


Functions 


ENQ is reissued to set this task in the “Must 
Complete” mode and ensure that any changes 
to SYSCTLG will be completed. 


This module consists of a series of tests for 
required functions. Each test calls the 
appropriate internal subroutine to perform 
one function if it is required. 


Chains of volume control blocks (VCBs) and 
index blocks are freed if possible; that is, they 
are set to zeros and rewritten into SYSCTLG. 
They then have a key of zero, indicating that 
they are available for use. 


If changes have been made to a generation 
index, the block containing the generation 
index pointer entry (GIPE) must be updated. 
Likewise, the last block of the generation 
index may need to be rewritten. 


If a generation index reached its maximum 
number of entries in |GGOCLC4 and the 
EMPTY option was specified, that option is 
processed. IGGOCLC4 will have already 
processed the DELETE option. 


If the generation index is full and the EMPTY 
option was not specified, the name with the 
lowest generation number (the oldest data 
set) is removed from the index. 


An UCATDX request can result in unneeded 
index blocks. Such blocks are freed. 


If a CATBX function is requested and the 
volume list contins more than five volumes, 
volume control blocks are constructed from 
that list and written to SYSCTLG. 
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Internal Subroutines 


WRBLKRTN, WRLSTRIN, EMPTYRTN, 
FRNDXRTN, FRVCBRTIN, FRBLKRTN, and 
BLVCBRTN are shown on the flowchart. 


SETUP points to the first and last entry in an 
index block. 


INCR increments the pointer to the next entry 
in an index block. 


TOABSL converts a relative track address to 
an absolute track address. 


TORLTV converts an absolute track address to 
a relative track address. 


10 performs EXCP input/output operations. 
This subroutine invokes 1GC0002H if a new 
extent is required. 

Exits 


Control passes via an XCTL macro instruction 
to: 


e IGGOCLC3 when the requested function is 
CATBX. 


e |IGGOCLC7 for error conditions. 
e IGGOCLC6 otherwise. 


Control passes via an SVC 28 to 1GC0002H 
when a new extent of SYSCTLG is required, 
and returns to this module. 


Error Conditions 


Code Reason 


20 Not enough space available in 
SYSCTLG to perform the requested 
function. 

28 Permanent I/O error. 
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IGGOCLC6: Second Load of Update 


IGGOCLC6 is the entry point. Control comes 
from: 


e IGGOCLC4 when the requested function is 
CAT, UNCAT, RECAT, or CATBX. 


¢ IGGOCLC3 or IGGOCLCS. 


Registers 


4 Base register for this module 

6 Base register for WORKAREA DSECT 
8 Base register for CAMLSTD DSECT 
12 Linkage register for BAL instructions 
14 Linkage register for BAL instructions 


Functions 


This module adds or deletes an entry to or 
from a given index block, as set up by earlier 
phases, and ripples the change through the 
index chain as needed. Each entry is taken 
from the buffer INPUT and placed into the 
buffer OUTPUT until the collating sequence of 
the entry is equal to or greater than the name 
in the update request. If the request name is 
equal, that entry is skipped (delete function). 
If the request name is greater, the new entry 
is merged into OUTPUT (add function). 
Overflow entries become an add request for 
the next block in the chain. 


Subroutines named GET and PUT are used for 
input/output. GET reads a block into INPUT, 

a field of WORKAREA, and initializes PUT. 
Entries are transferred from INPUT to 
OUTPUT, another field of WORKAREA. When , 
all entries have been exhausted from INPUT, 
another block of the index is read from 
SYSCTLG. 


When OUTPUT is full, a block is written to 
SYSCTLG from OUTPUT by the routine PUT. 
PUT checks all possibilities before writing the 
block and chooses the record of SYSCTLG 
that is most likely to result in contiguous 
blocks of one index. PUT tries to free any 
unneeded blocks; any unneeded block that 
PUT cannot free is later freed by GET. 
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Internal Subroutines 


GET reads one block from an index in 
SYSCTLG. 


PUT prepares and writes one block into an 
index in SYSCTLG. 


TOABSL converts a relative track address to 
an absolute track address. 


TORLTV converts an absolute track address to 
a relative track address. 


IO performs EXCP I/O operations. 


Exits 

Control is always passed to IGGOCLC7 via an 
XCTL macro instruction. 

Error Conditions 


The only exception code from this module is 
28, which indicates that a permanent 
input/output error has occurred. 
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IGGOCLC7: Third Load of Update and Error Handling 







IGGOCLC7 1s the entry point. Control rontco. 1s passed 

normally comes from IGGOCLC6, but can nuoore 

come from any module of catalog Ree tet 
management when an error condition is ~ 
discovered. 
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Functions 


IGGOCLC7 completes the update process. The 
last block of an updated index is written to 
SYSCTLG. 
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The block containing the index control entry 
(ICE) is read, and the ICE is updated to 
reflect changes to the index. This block is 
rewritten to SYSCTLG. 









The block containing the volume index MOVEICE 


control entry (VICE) is read, and the VICE is 
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block is rewritten into SYSCTLG. 
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If an error is discovered, pertinent 
information is gathered into an environment 
record and written to SYSCTLG. The 
exceptional return code is set and all 
resources are freed. Control returns to the 
caller of catalog management via an EXIT SVC 
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Internal Subroutines 
READ reads one block from SYSCTLG. 
WRITE writes one block to SYSCTLG. 


TOABSL converts a relative track address to 
an absolute track address. 


TORLTV converts a relative track address to 
an absolute track address. 


10 performs EXCP input/output operations. 
This subroutine invokes IGC0002H if a new 
extent of SYSCTLG is required. 


Error Conditions 


This module returns any exception code from 
another catalog management module to the 
caller. This exception code is passed to 
IGGOCLC7 1n WORKAREA. 


The only exception code from this module is 
28, which indicates that a permanent I/O 
error has occurred. 


Exits 


IGC0002H may be invoked via an SVC 28 when 
a new extent of SYSCTLG is required. Control 
returns to this module when one has been 
located. 


Control returns to IGC0002F via an XCTL SVC 
instruction. 
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IGCO0002H: SYSCTLG Open/Extend 


IGC0002H is the entry point. Control comes 
via an SVC 28 from: 


e IGGOCLCO or IGGOCLC3 to open a CVOL. 


¢ IGGOCLC3, IGGOCLCS, or IGGOCLC7 to 
extend SYSCTLG. 


Control also comes via an XCTL macro 
instruction from IGG0553E after extending 
SYSCTLG. 


Registers 
On Entry for Opening: 


Q Zero 
1 Address of UCB table for CVOL 
15 Address of area in which to build 
DCB/DEB chain 


On Entry for Extending: 
Q Address of DCB for SYSCTLG 


On Entry after Extending: 

QO Negative number 

4 Address of EXTEND work area 

9 Address of DCB for SYSCTLG 
10 TYR for new extent of SYSCTLG 
11 Address of UCB 


On Exit: 
1 Address of DCB/DEB chain 


Functions 


When this module is entered to open a CVOL, 
a data control block (DCB) and a data extent 
block (DEB) are built in the work area 
provided by IGGOCLCO. If the catalog is new, 
IGGOCLF?2 is invoked to format it. 


Note: The DCB/DEB constructed by this 
module is a modification of that described in 
OS/VSI System Data Areas. See Figure 12. 


When this module is entered to allocate 
another extent of SYSCTLG, a test is made to 
see if another extent already exists. If so, 
WORKAREA is modified accordingly, and 
control returns to the caller. 


When another extent does not exist, the main 
storage for the previous DCB/DEB is released 
and a new area is obtained with GETMAIN. 
IGG0553A is invoked to allocate a new extent, 
and a new DCB/DEB is built into the new 
area (the DCB/DEB is reopened). 


The DCB/DEB built by this module differs 
from that described in OS/VSiI System Data 
Areas. These two blocks are merged together; 
that is, they overlap in the same area of main 
storage, as shown in Figure 12. Main storage 
for the DCB/DEB is set to zeros before 
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Figure 12. DCB/DEB Built by IGC0002H 
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Area Assigned by 


building; then only the fields that are shown 
are filled in. The first 20 bytes of the DCB do 
not exist (shown by the dotted line), so the 
area Starts with offset 20 of the DCB. The 
DEB overlays the DCB at offset 40. The fields 
that are named are described in OS/VS! 
System Data Areas. 


Internal Subroutines 


GETMAIN gets main storage for the DCB/DEB. 


IO performs EXCP input/output operations. 
Exits 
Control returns to the caller via an EXIT SVC 


instruction when IGC0002H completes its 
function. 


Control returns to the caller via an EXIT SVC 
instruction for an error condition. 


Control passes via an XCTL macro instruction 
to: 


e IGG0553A when another extent is required. 
Control returns via an XCTL macro 
instruction to the entry point, IGC0002H 
(block Al of part A). 


e IGGOCLF2 when the catalog or new extent 
needs to be formatted. Control returns 
directly to the caller. 


Error Conditions 


Code Reason 

4 No extents are allocated. 

8 No more extents are available. 
12 Permanent I/O error. 
72 DOS-to-OS conversion was 


unsuccessful (returned by IGG0533A). 


IGG0553A through IGGO553E are invoked by 
this module and can also return exception 
codes. For details about these modules, refer 
to the publication listed below. 
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IGGOCLF2: SYSCTLG and BPAM Directory Formatter 


IGGOCLF2 is the entry point. Control comes 
from I1GC0002H. 


Registers 


Q Number of blocks to be written into a 
BPAM directory (zero when formatting 
SYSCTLG) 


1 Address of DCB for this data set 


2 Number of blocks per track for this 
device 


3. Number of bytes in work area passed to 
IGGOCLF2 


4 Address of work area 


5 Data management count decrement 
value 


6 Starting relative track address (TTR) 
when formatting SYSCTLG 


Functions 


The data set is formatted into 256-byte 
blocks with 8-byte keys. When formatting a 
BPAM directory, the module writes one block 
at a time. When formatting SYSCTLG, the 
module writes several blocks each time. 


If the extent is being formatted during an 
open CVOL request, then this is the first 
extent of SYSCTLG. The first block is 
initialized by writing a volume index control 
entry (VICE) into it. 


If formatting is not being done during an 
open request, then this is an extent of an 
already existing SYSCTLG. The VICE is read, 
updated, and rewritten to reflect the new 
extent. 


The work area that is passed to IGGOCLF?2 is 
freed before exit. 
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Internal Subroutines 


CNVT converts a relative track address to an 
absolute track address. 


10 performs EXCP input/output operations. 
RELOC builds channel programs for 
input/output. 

Error Conditions 


IGGOCLF2 returns one exception code, 12, 
which indicates that an I/O error has 
occurred. The caller of catalog management 
never sees this code. 


Exits 


Control is passed to the caller of IGC0002H 
via an EXIT SVC instruction. 
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Microfiche Directory 


This chapter helps you relate the discussions in this book to the assembly listings 
found on microfiche. The rightmost columns of this directory contain page 
number references to Method of Operation figures and/or flowcharts where more 
information can be found. The microfiche are found under the component name 
“Data Management.” 















Module/ 
Entry Point (Microfiche Method of Flowchart 
Name Name Description Operation Page Page 

IGC0002F IGC0002F Controller I to route catalog 20 32 
requests 

IGC0002F IGC0002F Controller II to route catalog 20 
requests 

IGGOCLCA |IGGOCLCA Controller II to resume 
processing of OS/VS requests 

IGGOCLCB' |IGGOCLCB Controller II to resume 
processing of VSAM requests 

IGGOCLCO |IGGOCLCO | Initialization for catalog 20 = 
management routines 

IGGOCLC1 IGGOCLC1 Relative GDG and alias 

IGGOCLC2 IGGOCLC2 

IGGOCLC3 IGGOCLC3 Update initialization and entry 46 
building 

IGGOCLC4 |IGGOCLC4 Entry building 22 48 


IGGOCLCS IGGOCLCS5 First load of update 22, 23 0 
IGGOCLC6 IGGOCLC6 Second load of update 22, 23 52 


IGGOCLC7 = |IGGOCLC7 Third load of update, exit 
processing, and error handling 
1GC0002H _|IGC0002H _|SYSCTLG open or extend 
IGGOCLF2 IGGOCLF2 SYSCTLG and BPAM 20 58 
directory formatter 










































; 
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Data Areas 


The data areas and record formats in this chapter are described in four columns, 
which are interpreted as follows: 


Offset 


The numeric address of the field relative to the beginning of the area. The 
first number is the offset in decimal, followed (in parentheses) by the 
hexadecimal equivalent. 


Bytes and Alignment 
The size (number of bytes) of the field and its alignment relative to the fullword 
boundary. 


Examples: 
4 A 4-byte field beginning on a word boundary. 
.3 A 3-byte field beginning on a halfword boundary and running into the 
next word. 


.2 A 2-byte field beginning at the low-order byte of a word and running 
into the next word. 


Name and Content 
A name that identifies the field. This name appears as a label in the assembly 
listings for the catalog management routines. 


This column is also used to show the contents of the field or the bit settings of 
flag fields (the state of bits in a byte). When thé column is used to show the 
state of the bits (O or 1) in a flag byte, it is shown as follows: 


ae The 8 bit positions (0-7) in a byte. For ease of scanning, the 
high-order (leftmost) 4 bits are separated from the low-order 4 bits. 

Misi se A reference to bit 0. 

| Peers Bit 0 is on. 

0... 0... Bit O is off. 

site es xx A reference to bits 6 and 7. 


Bit settings that are significant are shown and described. Bit settings that are 
not presently shown are understood to be reserved bits. 


Field Description and Meaning 
The use of the field. 


SYSCTLG Entry Formats 


This section describes the formats of the entries of SYSCTLG, along with the 
symbolic labels that are used to refer to their fields. The entries are arranged 
alphabetically. 


Except for the volume control block (VCB), SYSCTLG entries have a similar format. 
These entries share a common definition for the first 12 bytes. The shared names 
are: 


ENAME ETTR ETYPE 
(8 bytes) (3 bytes) (1 byte) 


Individually named fields follow either ETTR or ETYPE. 


The entries in a SYSCTLG block begin in the third byte of the block. The first 
halfword of the block contains the binary number of the bytes that are used in this 
block, including the halfword count field. 
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Alias Entry (AE) 


An alias entry defines an alternate name for the high-level qualifier of a data set 
name. 


Bytes and = |Name and 
Alignment (Content Field Description and Meaning 


ENAME Name; contains the alias of the high-level 
index whose relative track address is found at 
offset 8 of this entry. 















Address; contains the relative track address 
(TTR) of the first block of the index named at 
offset 12 of this entry. 


8(8) ETTR 
Type; indicates that this is an alias entry; also 
that four halfwords follow in the remainder of 


ETYPE 
x‘04’ 
the entry. 
12(C) ETRUEN [True name; contains the name of the index 
whose alias appears at the beginning of this 
entry. 


Control Volume Pointer Entry (CVPE) 


A control volume pointer entry can appear only in volume indexes. Two forms are 
possible: the old form, created prior to Release 17 of IBM System/360 Operating 
System, and the new form, created since that release. Both forms are shown here. 


ge 
Alignment (Content Field Description and Meaning 


= | _ 
X‘000000" 
This is also the number of halfwords that 


ETYPE 
x‘03’ 
follow in the remainder of the ent 


12(C) EVOLIDO |Serial number of the control volume whose 
volume index contains an entry for the name 
found at the beginning of this entry. 


Bytes and 
Alignment Field Description and Meaning 
ENAME __ |Name; contains a high-level name that 
appears in the volume index of the control 
volume identified at offset 12 of this entry. 


X‘000000' 


af Type: indicates that this is a new CVOL 


pointer entry (CVPE) or the volume index 
control entry (VICE). The VICE always 
12(C) i EDEVTYP 
iat Oe _ 


appears as the first entry in the first block of 
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Old CVOL Pointer Entry 







Name field; contains a high-level name that 
appears in the volume index of the control 
volume identified at offset 12 of this entry. 














Type; indicates that this is either an old CVOL 
pointer entry (CVPE), or an index control 
entry (ICE). An ICE always appears as the 
first record of an index level; a CVOL pointer 
entry always appears in the volume index. 










New CVOL Pointer Entry 





















SYSCTLG; a CVOL pointer never appears as 
the first entry of the first block. Also 
indicates that five halfwords follow in the 
remainder of the entry. 


Control volume device type; contains the 
binary device code of the control volume 
whose volume index contains an entry for the 
name found at the beginning of this entry. 













Serial number of the control volume whose 
volume index contains an entry for the name 
found at the beginning of this entry. 









Data Set Pointer Entry (DSPE) 


A data set pointer entry can appear in any index level. It contains the simple name 
of a data set and from one to five 12-byte fields, each of which identifies a volume 
on which the named data set resides. 


Bytes and Name and 
Alignment (Content Field Description and Meaning 
7 oe _ 


8(8) EDSCBTTR 





Name; contains the simple name of the data 
set whose volumes are identified at offset 12 of 
this entry. 












Address; contains either binary zero or, when 
the data set resides on only one volume, the 
relative track address (TTR) of the data set 
control block (DSCB) for this data set in the 
volume table of contents (VTOC). 








Type; indicates that this is a data set pointer 
entry (DSPE). Also indicates the number of 
halfwords that follow in the remainder of this 
entry. 





















Volume count; contains the binary count of 
the number of volumes identified beginning at 
offset 14. 


Volume entries: contains from one to five 
12-byte entries, each of which identifies one 
volume on which the data set resides. Catalog 
management neither uses nor checks the 
contents of this field. 


12(C) EVOLCNT 


: - 


Generation Index Pointer Entry (GIPE) 








A generation index pointer entry can appear in any index except a generation 
index. It corresponds to the simple name used in the relative name for a GDG data 


Bytes and =| Name and 
Alignment [Content Field Description and Meaning 


a eae 


12(C) he EGFLAGS 
aa — 
14(E) EGCURSIZ 





Name; contains the name of the generation 
index to which this entry points. 


Address; contains the relative ‘rack address of 
the first block of the generation index named 
in the form TTR. 


Type; indicates that this is a generation index 
pointer entry (GIPE). Also indicates that two 
halfwords follow in the remainder of this 




























Flags; contains the options specified by the 
creator of the generation data group: 


DELETE option. 








Maximum count; contains a binary number 
specifying the maximum number of 
generations allowed in the generation index at 
one time. 





Current generation count; contains the binary 
number of generations currently cataloged in 
the index. 
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Index Control Entry (ICE) 


The index control entry is the first entry in all indexes except the volume index. 


Bytes and |Name and 
Alignment [Content Field Description and Meaning 
0(0) g INAME Name; low value of binary | ensures that this 
X‘00...01' lis the first entry in the index. 
8(8) 3 ILSTBLK Last block address; contains the relative track 
address of the last block assigned to the index, 
in the form TTR. 


11(B) ITYPE Type; indicates that this is either an ICE or an 
X‘03’ old CVOL pointer. An ICE always appears as 
the first entry of an index; an old CVOL 
pointer always appears in the volume index. 
Also indicates the number of halfwords that 
follow in the remainder of the entry. 
























12(C) 3 IFSTBLK _ |First block address; contains the relative 
address of the block in which this entry 
appears, in the form TTR. = 

15(F) ILIASCNT |Number of aliases; contains a binary count of 
aliases assigned to the index. This count is 
always zero for indexes that are not high-level. | 
An index cannot be deleted if this count is 
non-zero. 

wot | 2 | Reserved. 


Index Link Entry (ILE) 


An index link entry is always the last entry in any index block. It is used to link 
blocks of one index into a chain. 


Bytes and Name and 

Alignment Content Field Description and Meaning _ 

ENAME Name; high value (all bits on) ensures that this 
X‘FF...FF [is the last entry in the index. 


8(8) Link address: contains the relative track 













address of the next block of the same index, if 
there is one, in the form TTR. When this is 
the last (or only) block, this field contains 
binary zero. 











Type; indicates that this is either an ILE or an 
IPE. The name field of an ILE always 

contains X‘FFFFFFFFFFFFFFFF ; the name 
field of an [PE never does. Also indicates that 
there are no more halfwords in the entry. 






Index Pointer Entry (IPE) 


The index pointer entry can appear in any index except a generation index. It 
points to a lower index. 


Bytes and = (Name and 
Alignment /|Content Field Description and Meaning 
pm 8 ENAME Name; contains the name of the index to 
which this entry points. 
8(8) = |e | Index address; contains the relative track 


address of the first block of the index named 
ETYPE 
X‘00’ 


in this entry, in the form TTR. 
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Type; indicates that this is either an IPE or an 
ILE. The name field of an ILE always 
contains X‘FFFFFFFFFFFFFFFF ; the name 
field of an IPE never does. Also indicates that 
there are no more bytes in the entry. 


c 


Volume Control Block (VCB) 


A volume list can be recorded in one or more volume control blocks. Each volume 
control block is one block of the SYSCTLG data set, and can identify up to 20 
volumes on which one data set is recorded. 


Note: This block is different from other blocks of SYSCTLG. The first halfword 
does not contain the number of bytes used in the block as do other SYSCTLG 
blocks. The field VCBVOLCT, shown below, is the first halfword of the VCB block. 


Bytes and Name and 
| Alignment Content Field Description and Meaning 


0(0) 2 VCBVOLCT |Number of volumes; contains the number of 
volumes identified in this and subsequent 
volume control blocks. This number is 

| reduced by 20 for each subsequent volume 
control block. For example, if a data set 
resides on 61 volumes, it uses four volume 
control blocks. This field of each block 
contains 61, 41, 21, and 1, respectively. 

2(2) ..12 to 240 VCBVOLS [Volume identifications; contains from 1 to 20 
12-byte entries, each of which identifies one of 
the volumes on which the data set resides. 
Catalog management neither uses nor inspects 
the content of these entries. Each 12-byte 
entry contains a 4-byte device code, a 6-byte 
volume serial number, and a 2-byte data set 
sequence number. 


242(FC) Chain address, contains the relative track 


address of the next volume control block, if 







































there is one, in the form TTR. If this is the 
last (or only) block of the volume control 
block, this field contains binary zero. 


Zero field. 





Volume Control Block Pointer Entry (VCBPE) 


A volume control block pointer entry can appear in any index. It is used when a 
data set resides on more than five volumes. 


Bytes and Name and 
Alignment /Content Field Description and Meaning 


Name; contains the simple name of the data 
set whose volumes are identified in the volume 
control block that is pointed to by this entry. 









Address; contains the relative track address of 
the volume control block identifying the 

volumes containing the data set named in this 
entry, in the form TTR. 


Type; indicates that this is a volume control 
block pointer entry. Also indicates that one 
halfword follows in the remainder of this 

ent 


Zero field. 
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Volume Index Control Entry (VICE) 


The volume index control entry is always the first entry in the first block of data 
set SYSCTLG. 


It is the control record for the entire data set, and acts as an ICE for the volume 
index. 


Bytes and (Name and 

Alignment (Content Field Description and Meaning 
- 2 
7 







Name; always contains a binary one to 
ensure that this is the first entry of the 
volume index. 












Last block address; contains the relative track 
address of the last block of the volume index, 
in the form TTR. 


Type; indicates that this is the volume index 
control entry or a new CVOL pointer entry. 
The volume index control entry is always the 
first entry of the first block of SYSCTLG; a 
CVOL pointer is never the first entry. Also 
indicates that five halfwords follow in the 
remainder of the entry. 


VCLSTBLK |Last block of the catalog; contains the 
relative track address of the last block in 
SYSCTLG, in the form TTR. 


Contains the number of TTRs in 


~ 

14(E) VHIREC 
VCLSTBLK. Note that this field is the last 
byte of VCLSTBLK (offset 12). 























15(F) Zero field. 


16(10) VFHOLE _|First available block: contains the relative 
track address of the first unused block in 
SYSCTLG, in the form TTR. 


19(13) Zero field 
20(14) en Reserved 


Environment Record (EREC DSECT) 


The environment record is written by module IGGOCLC7 under certain error 
conditions. This record is useful in diagnosing problems using the catalog 
management routines. Reading the environment record is described in the 
chapter, “Diagnostic Aids.” 


Bytes and |Name and 
Offset Alignment (Content Field Description and Meaning 


Bo eal 


16(10) 

























Reserved. 











Time stamp, as produced by the TIME macro. 
instruction. 










ERCAMLST | First four bytes of the caller's parameter list 


produced by the CAMLST macro instruction 
(see description of CAMLSTD on page 67). 


ERMODMAP |Field MODMAPI1 from WORKAREA, 
described on page 72. 
ERFLAGI /|Field FLAGI from WORKAREA, described 
on page 70. 
22(16) ERFLAG2 _ |Field FLAG2 from WORKAREA, described 
on page 71. 
23(17) ERFLAG3 /|Field FLAG3 from WORKAREA, described 
on page 70. 
24(18) 2 ERERRCOD |Fields ERRCATSV and ERRLOCSV from 
WORKAREA, described on page 55. 
26(1A) ERNAMTTR |Level name, TTR, type, and volcnt; the first 
14 bytes of a general entry. 


40(28) ERREGSV {Contents of general registers 0 through 14 at 
the time the environment record is written 
(register 15 is destroyed by module 
IGGOCLC7). 

100(64) ERWAI Contents of WORKAREA from offset 12 
bytes (label TTR) through offset 39 bytes. 
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CAMLSTD DSECT 





(cont.) 





Bytes and (Name and 
Alignment (Content Field Description and Meaning 
128(80) PB ERINPUT {First entry in INPUT, a field described on 
page 72. 
146(92) pe EROUTPUT ||First entry in OUTPUT. a field described on 
page 72. 
164(A4) Ls 3 EROPTNCC |Field OPTNCCW from WORKAREA, 
described on page 72. 
176(B4) oe ERIOB Field JOB from WORKAREA, described on 


page 72. 
212(D4) ERNAME 


Fully qualified name provided by the caller. 







































CAMLSTD describes the parameter list provided by the caller of catalog 
management. It maps the result of the CAMLST macro instruction. 


Bytes and = |Name and 
Alignment /|Content Field Description and Meaning 


CAMOPTNI |First option byte. 

ie Catalog ts not on SYSRES. 
CAT or CATBX request. 
RECAT request. 
UNCAT or UNCATDX request. 
Locate-by-block request. 












BLDX or CATBX request. 
BLDG request. 

BLDA request. 

LNKX request. 

DLTX or UCATDX request. 
seals DSCB TTR has been specified. 
sie Sud DLTA request. Dot ee 
er DRPX request. 

Scratch GDG dala sets. 


Empty generation index when maximum 
gencralion count is reached. 


Search VS catalog first. 
ea eels Search only one catalog. 
secant VS CAMLST } 
bicsanSiat __|VSAM parameter list. 
CAMGEN 
CAMPTRI 





Maximum generation count. 
Address of the name field in caller's area. 
For locate-by-block, the name field contains a 
relative track address instead of a name. 


CAMCVOLP |Address of CVOL volume scrial number (a 
6-byte field). 


Address of caller's third parameter. Meaning 
depends on the function: 





CAMPTR3 


Locate Callers 265-byte work 
area 

BLDA 8-byte name field 
LNKX 10-byte volume 
identification 

CAT, CATBX 

or RECAT Volume list 

Other Not used 


CAMDSCBP |Address of three-byte field containing the 
relative track address (TTR) for the Format | 
DSCB for the data set named through 
CAMPTRi. 
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RPSD DSECT 


WORKAREA DSECT 


RPSD describes the CCW chain used for rotational positioning sensing (RPS) 
support. 


Bytes and Name and 
Alignment (Content Field Description and Meaning 


RPSCCW_ |Two double-words: RPSSS and RPSTIC 
RPSSS _—‘{Set sector CCW. = 
RPSTIC TICs to normal channel program. 


RPSINPUT |Four words: RPSCNVT, RPSDDKR RPSRI 
and RPSPTR. 


Address of supervisor routine to convert sector 
value. 


Block size (DD, 256 bytes). key length (K_ & 
bytes), and record number. 


Address of location of this DSECT during use 





































RPSCNVT 


RPSDDKR 



















Type and address: the first byte contains the 
device type code, and the last three bytes 
contain the sector value. _ 










32(20) 10-word register save area. 





WORKAREA serves all catalog modules. WORKAREA Serves as intermediate 
storage, communications area, and buffers. BLDLAREA is a portion of WORKAREA 
that serves the resident BLDL routines. For a locate function, BLDLAREA is 
separate from WORKAREA. 


Many of the fields in the area overlay other fields, and sections of an area can have 
more than one label. Figure 13 shows where these overlays occur, by label The 
listing for any module shows more labels and more detail; only the most significant 
are shown here. 


s en function is non-locate, one area (GETMAIN) 
“Ng used for all purposes. 


When function is locate, two areas are used. Space 
“td for BLDL comes from GETMAIN. 


WWORKAREA 
The caller's area is used for WORKAREA 


4 


AAT DATA 
Wie caller's area is redefined as RETDATA 
‘bg pass data back to the caller. 





EE LT a Sh we oa KK — — 


Figure 13. Data Area Hierarchy 
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Bytes and |Name and 
Alignment (Content Field Description and Meaning 


BLDLIST  |List parameter for BLDL or. when 
SAVETTR3 /appropriate, the name of the last valid index 
level. - 
NAME Name itn the entry that is being operated on, 
ALIASNAM lor the alias. . 


5(5) GENNO Generation number portion of an absolute 
GDG name. > 


12(C) Relative track address in the current entry, in 
the form TTR. 


15(F) TYPE Type of entry; also the binary number of 
halfwords following in the remainder of the 
entry. TYPE is interpreted as: 

X 1F DSPE with five volumes. 
TRUE The true name to which the alias in offset 4 
relates. 
2 VOLCNT  |Number of volumes identified in DATA when 
the current entry is a data set pointer entry 
(DSPE). 
DATA Volume identifications for DSPE. 
ERRCATSV |Error code generated for non-locate function. 
ERRLOCSV [Error code generated for locate function. 


Switches declaring requested function. 














either an index pointer entry (IPE) or an index 
link entry (ILE). The name field of an ILE 
always contains X'FFFFFFFFFFFFFFFF ; the 
name field of an IPE never does. 


Volume control block pointer entry (VCBPE). 
Generation index pointer entry (GIPE). 


Index control entry (ICE) or old CVOL 
pointer entry (CVPE). An ICE always appears 
as the first entry of the index: a CVPE always 
appears in the volume index. 


Alias entry (AE). 


Volume index control entry (VICE) or new 
CVOL pointer entry (CVPE). The VICE 
always appears as the first entry of the first 
block of the catalog: a CVPE always appears 
later in the volume index. 


Data set pointer entry (DSPE with one volume 
identification). 


DSPE with two volumes. 
DSPE with three volumes. 
DSPE with four volumes. 






16(10) 


16(10) 
88(58) 
89(59) 
90(5 A) 


The index control entry (ICE) must be read. 


SYSCTLG has no more room during CATBX 
or BLDX function. 


The DCB/DEB was freed by SVC 28 


processing. 
CATBX request. 
UCATDX request. 


Locate request. 


RECAT request. 





(cont.) 
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(cont.) 


Bytes and Name and 
Alignment (Content Field Description and Meaning 
Generation index pointer entry (GIPE) has 


: | 
been found. 


92(5C) pe SAVEAREA pave area for temporarily storing the contents 
pose registers. 
120(78) Le NEXTKEY |The key or count of the next block beyond the 


NEXTCNT ione read. 
= [= | 
_ a 


i 
TE The block following the block pointed to by 
field LINKTTR is free. 


Biel MEI: NAMLEN rua of the full name given by caller minus 


NAMDELMP a of last delimiter nen in given name. 
80 | NAMLSTP | Pointer to last displacement of given name in 


er name table. 
ae |Switches to specify flow of control in 
IGGOCLC7. 
rea ee Low-level index is involved. 
era VFHOLE needs to be updated. 
ee LSTBLK needs to be updated. 
FSTBLK needs to be updated. 
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Switches used to specify flow of control. 


RPS device. 







‘(’ has been found in the data set name. 


Last entry found was a CVOL pointer entry 
(CVPE). 

















Index control entry; see the description on 
page 64 for individual fields. Only bytes 8 
through 15 are saved here. 





Volume index control entry; see the 
description on page 66 for individual fields. 
bytes 11 through 18 are saved here. 


Switches to invoke functions of IGGOCLCS. 
Absolute GDG name found. 








Free index blocks. 










Read a block for updating. 


Process EMPTY option of generation data 
group (GDG). 


Write the last block of aGDG chain when the 
GDG is full and a new one is being added. 


Build volume control blocks (VCBs). 
Free VCBs. 


Write a block. 


Switches to specify the flow of control in 
IGGOCLC6. 


New entry has been inserted into block now in 
the work area. Updating is in process. 





The updated block has been written into 
SYSCTLG. Updating is compleie. 


The block following the block pointed to by 
field WRITETTR is free. 


The first write has occurred. 





(cont.) 





(cont.) 


Bytes and (Name and 
Alignment [Content Field Description and Meaning 
ail 


162(A2) MODMAPI Trace of modules that have been entered. The 
appropriate bil is set to | as each module is 
entered. There is no bit for module 1GC0002F 
or IGGOCLCO, because these modules are 
always entered before any other. 


anh. Gaia IGGOCLCI 
IGGOCLC2 
IGGOCLC3 
IGGOCLC4 
IGGOCLC5 
IGGOCLC6 


IGGOCLC7 


Address of the entry point of the supervisor 
routine BLDL, IECPBLDL (copied from field 
CVTPBLDL of the CVT). 


Address of the list to be completed by BLDL 
(address of field BLDLIST, offset 0 of this 
DSECT). 


Address of the data control block (DCB) for 
the control volume. 

DEBADDR |Address of the data extend block (DEB) for 
the contro! volume. 


FOUNDENT |Address of an entry in an input/output buffer. 


























164(A4) EPBLDL 






BLDLISTP 









DCBADDR 


176(BO) 


180(B4) 


184(B8) EPTORLTV | Address of the entry point IECPRLTV, a 
supervisor routine that converts absolute track 
addresses to relative track addresses (copies 
from field CVTPRLTV of the CVT). 

188(BC) EPTOABSL |Address of the entry point IECPCNVT, a 
supervisor routine that converts relative track 
addresses to absolute track addresses (copied 
from field CVTPCNVT of the CVT). 


_ 


Address of the extension to the SVRB. 


i9xco | 4 _—i| SVRBEXTP 
Address of new entry, meaningful only when 


196(C4) a ae ADDING 
bit 0 of FLAG4 is ‘I’. n 
200(C8) i en XCTLPARM |Parameters for XCTL SVC. 


216(D8) LNKENTRY |General form in index link entry (ILE). The 
first eight bytes contain 
X*'FFFFFFFFFFFFFFFF . 
224( EO) = 4 LINKTTR |Last four bytes of LNKENTRY; contains the 
TTR for this ILE. 
228(E4) ae WRITETTR |Save area for relative address of block to be 
written. 


232(E8) k 


236(EC) 


a a 

















Relative track address of block that contains 
an index control entry (ICE). _ 


Save area for any relative track address. 


Save area for relative address of block to be 
read. 





244(F4) Pointer to catalog controller. _ 
248(F8) NAMLF Number of levels of the name that were found. 
250( FA) NAMLG Number of levels in given name. 


252(FC) 4 _| DEVTYPE |Device-type portion of an identification. 








256( 100) | THETA Angular displacement value (theta) for 
rotational positioning support (RPS). 
257(101) INDEXLEN |Length of all levels given except the last. Used 
with SCRATCH macro instruction. 
(cont.) 
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(cont.) 


Bytes and |Name and 
Alignment Content Field Description and Meaning 
258( 102) a ERRSV2H =| Exceptional return code from module 
1GC0002H. 
259 103) ae VOLSN __|Serial-number portion of a volume 
identification. 


16(10) DSNAME _|Data set name to be scratched (when 
processing GDG data sets). 


~ 


SCRPARM |Parameter list for SCRATCH macro 
instruction. 








60(3C) 12 





72(48) SCRVOLS [Volume list for SCRATCH macro instruction. 
32(20) NAMTABLE |Name table containing the length and 
displacement of each component of the given 
name. 
76(4C) NAMDELIM |Last delimiter in the given name, either ‘6’ or 
‘C. 
128(80) RELNUMBR |Work area for Convert-to-Binary instruction 
used with relative GDG processing. 
136(88) PKDNUMBR |Work area for Pack instruction used with 
relative GDG processing. 
(0) 256 RETDATA !Volume list returned to caller. 
252(FC) REDSCBT {Relative track address of the DSCB in the 


VTOC for a single-volume data set, as 
returned to the caller. 


RETCVOL /|Serial number for the control volume 
containing the returned volume list. 

VICESAVE |Save area for volume index control entry 
(VICE) information. 


BALREGS | |Save area for register used in BAL instruction. 


BLDLAREA [Work area for use by BLDL routine; for a 
locate function, WORKAREA is in two parts, 
and BLDLAREA is the second part. 


BLDLCNT  |Parameters for BLDL routine. 


BASESAVE |Save area for the register that would otherwise 
be destroyed by BLDL. 


RESALIAS_ |Work area used when resolving an alias name. 


INPUT 
TRTABLE {Translate table used with TR instruction to 













268(10C) 
272(110) 


528(210) 
648(288) 


536(218) 
272(1 10) 
272(110) 


528(210) 
536(218) 
544(220) 


TICI 


OPTNCCW /|CCW that is changed to do the required 
input/output function. 


Read-Count CCW. 
Search-Key-Equal CCW. | 


TIC2 

NOP 
Input/output block for channel programs. 

Read-Key-Data CCW. 

Read-Data CCW. 


WKD Write-Key-Data CCW. 
OUTPUT |Output buffer for channel programs. 


552(228) 


‘o) 


568(238) 
$76(240) 
584(248) 
588(24C) 
630(274) 
638(27C) 
644 

652(28C) 
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Diagnostic Aids 


Reading Dumps 


Main Storage Dump 


Page of SY35-0003-2, Revised October 1973, By TNL SN35-0011-0 


This chapter provides several aids that can be useful when diagnosing difficulties 
with the catalog management modules. These aids tell you: 


e What to look for in a main storage dump. 
e How to dump the SYSCTLG data set. 
e A description of an environment record that is written when an error is detected. 


¢« How to determine what modules are involved in a particular case and what the 
flow of logic is between them. 


Two kinds of dumps can be used while diagnosing trouble with catalog 
management routines: main storage dumps and SYSCTLG data set dumps. This 
section points out significant diagnostic clues to look for. It does not explain the 
full meaning of dumps; for that information, see OS/VS! Debugging Guide, 
GC24-5093. 


Main storage dumps are rarely helpful. Unless the error that caused the ABEND 
was actually in one of the catalog management routines, the transient areas (or 
paging areas) will probably have been used by another module of the operating 
system. 


If, however, an ABEND dump was produced because of an error in one of the 
catalog modules, then look at the content of the general registers at the time of the 
ABEND. The most significant registers are: 


Register 4 —_ Base register for all catalog management routines. This register 
points to the module that failed. 


Register 6 Pointer to WORKAREA (described on page 68. The field MODMAPI 
shows which modules have been entered; compare this to the 
expected path for the requested function. The section ““Module 
Selection Charts,” on page 76, shows the path for each function. 


Register 8 Pointer to caller’s CAMLST, described on page 67. Check the 
parameters in CAMLST carefully to be sure that the requests are 
valid. 


Have the following items available before requesting additional assistance: 


e Source or input listing for the use of catalog-management routines (be sure 
MSGLEVEL=(1,1)). 


e Main storage dump produced by using a SYSABEND DD statement. 
e Dump of SYSCTLG data set. 


Diagnostic Aids 73 


SYSCTLG Dump 


There are several ways to dump a data set; this discussion assumes that HMASPZAP 
is used. (In VS1, the program is HMASPZAP; in VS2, the program is AMASPZAP.) 
HMASPZAP is a Service-aid program that operates under the operating system. 
HMASPZAP is described in OS/VS; Service Aids, GC28-0633. 


To dump the catalog with HMASPZAP, use the following JCL, where the SYSLIB DD 
card points to the CVOL to be dumped: 


//DUMPSTEP EXEC PGM=HMASPZAP 
//SYSPRINT DD SYSOUT=A 
J/SYSLIB DD DSNAME=SYSCTLG, UNIT=xxxx, 
Pes VOL=SER=XxXXxXxXx,DISP=OLD, 
DCB=( KEYLEN=8 ) 

F{SYSIN DD * 

ABSDUMP ALL 
/* 
This JCL is used to dump the entire catalog; you can dump a portion by specifying 
beginning and ending track addresses. 


The DCB parameter KEYLEN in the SYSLIB DD statement formats the Key as well 
as the data for each block. The key appears as the first two words of the first line 
of each block. The data for the block begins in the third word. 
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Example of a SYSCTLG Dump 


Figure 14 shows an actual dump of the catalog. Entries in the volume index are 
outlined, and other blocks of the catalog are identified. 







































KEY CNT VICE IPE ILE CVPE 
DSPE “SCCHHR- 9001000601 __ RECORD _LENGTH- 0108 ws 
Q00 [‘FFFFFPFF  FFFFFFFF | '0074p000_' 00000000 __|_p0010000 01050000 __11000000 
00002 4CSD7E3 40404040 00000007 __—-00013000__—| f2001C4Ea —DSESD6D3_—_—0000ESD5_~ ESDSE3D6 | Alias 
000040 , D9E80000 00053000 2001FOFO FOFOFOF1 D7C1E8D9 D6D3D330 00000200 | D7D940ee—7 
000060 © 40404040 000002048 D7C1£Z8D9 D6D3D340 FFFFFFFF FFFFFFFF 00000000 | 00000000 
000080 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
0000A0 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
o000cO | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
Q000EO } 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 





























000100 | 00000000 00000000 CNT ee 
KEY ~8*CCHHR- 0001000602 RECORD LENGTHS 0108 First block of 
000 D3C9E2E3 40404040 | OOFEDO00 00000000 00010000 % 02030000 _02010000 T c1oscxca = "index ‘PAYROLL’ 
000020 | C9E5C540 0000001F 00053000 2001C4Ea D4E5D6D3 00003000 2001CaE4 E5D3F1 
000040 | 00003000 2001C4B4 D4ESD3IF2 000030C0 2008E5C3 C2C3D2F1 000030CO 2008E5C3 
000060 | C2c3D2F2 0000D3C1 C2D6D9480 40400000 001F0005 30002001 C4EaDaES D6D30000 
000080 | 30002001 C4E4D4E5 D3F10000 30002001 C4E4D4E5 D3F20000 30C02008 = £5C3C2C3 
OOOOAO | D2F10000 30C02008 £E5C3C2C3  D2F20000 D3IC9E2E3 40404040 0000001F 00053000 
0000Cc0 200 1C4E4 D4ESDED3 00003000 200 1C4E4 D4ESD3F1 00003000 2001C4E4 D4ESDIF2 
QOOOEO | 000030CO0 200885C3 C2C3D2F1 000030C0 2008E5C3 C2C3D2F2  OOOOFFFF  FFFFFFFF 
000100 | FFFFO00O0 03000000 
KEY **CCHHR- 0001000603 RECORD LENGTH- 0108 
~ QOOUUO—~= FFFFFFFF FFFPFFFF | O0COD4D6  D5EIC8D3 E8400000 001F000S5 30002001 C4E4D4ES Second block of 
000020 | D6D30000 30002001 C4E4D4ES D3F10000 30002001 C4E4D4E5 D3F20000 30602008 i doy ‘"PAYROLL’ 
000040 | E5C3c2C3 D2F10000 30C02008 = E5C3C2C3 D2F20000 D9C5D7D6 D9E34040 0000001F 
000060 | 00053000 2001C4E4 D4ESD6D3 00003000 2001C4E4 D4ESD3F! 00003000 2001C4E4 
000080 | D4ESD3F2 000030CO 2008E5C3 C2C3D2F1 000030CO 2008E5C3 C2C3D2F2 0000E2Cc1 
OO}OUAO | D3C1D9EB 40400000 04010000 E3Cc9D4Cc5 C3C1D9C4 ~=—-00000502 =: 000050004” FFFFFFFF 
0000CO | FFFFFFFF 00000600 00000000 00000000 00000000 00000000 00000000 00000000 
O000EO | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
000100 | 00000000 00000000 VOLCNT 
KEY **CCHHR- 0001000604 RECORD LENGTHY 0108 
0 FFFFFFFF  FFFEFFFF | 0007B000 2001C4E4 D&ESD6D3 00003000 2001C4E4 D4E5SD3F1 
000020 | 00003000 2901C4E4 D4E5D3F2 000030C0 2008E5C3 C2C3D2F1 000030CO 2008E5C3 
000040 | C2C3D2F2 000030CO 2008E5C3 C2C3D2F3 000030CO 2008E5C3 C2C3D2F4 00000000 
000060 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 _ 00000000 Volume contro! 
000080 | 00000000 00000000 00000000 00000000 00009000 00000000 00000000 00000000 block 
0000A0 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
0000c0 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
OQO0O00EO | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
000100 | 00000000 00000000 
**CCHHR- 0001000605 RECORD LENGTH- 0108 
KEY —gogeee—"FrFFPFFF FFFFFFFF | 00880000 00000000 00010000 05030000 05000000 C7OFOFOF 
000020 f[ OBESFOFO 00000007 00013000 2001C4E4 D4E5D6D3  O0000C70F OFOFOCES FOFO0000 
000040 | 00070001 30002001 CA4EaD4E5 D6D30000 C7OFOFOF ODESFOFO 00000007 00013000 
000060 | 2001C4E4 D4E5D6ED3 O000C70F OFOFOEES FOFOO0000 00070001 30002001 CaE4D4E5 
000080 | D6D30000 «SO FFFFFFFF- = =FFFFFFFF 00000000 00000000 00000000 00000000 _ 00000000 
QO000A0 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000066 Generation index 
0000CO0 }| 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
QO000EO } 00000000 00000000 00000000 00000000 00000000 00000000 _0900C000 _ 00000000 
000100 | 00000000 00000000 
**CCHHR- 0001000606 RECORD LENGTH- 0108 
200000 FFFFFFFF FFFFFFFF | OOA2E3D6 £E3C1D3E2 40400000 001F0005 30002001 C4E4D4E5 
KEY ~So0020 Ppen30000 30002001 C4E4D4E5 D3F10000 30002001 C4E4DaES D3F20000 30C02008 
000040 | E5C3C2C3  D2F10000 30C02008 £5C3C2C3 D2F20000 ES8D9E3D6 C4CIE3ICS 0000001F 
000060 | 00053000 2001C4E4 D4ES5D6D3 00003000 2001C4E9 D4E5D3F1 00003000 2001C4E4 
000080 | D4E5D3F2 900030CO 2008£5C3 C2C3D2F1 000030CO 2008€5C3 C2C3D2F2 OOOOFFFF 
QOOOAO | FFFFFFFF FFFFOO00 00000000 90000000 00000000 00000000 00000000 , 
0000cO | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 Third block of P 
0000EO | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 index “PAYROLL 
000100 | 00000000 00000000 
**CCHHR- 0001000607 RECORD LENGTH- 0108 
0000 0000000 00000000 [ 00000000 ~~ 06000000 00000000 ~=—«00000000 = 00000000 ~—-00000000 
KEY —se0020 POSSESS 00000000 00000000 00000000 00000000 00000000 00000000 00000000 
000040 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 0000000 
000060 | 00000000 00000000 00000000 00000000 00000000 00000000 00000000 a block of 
“Aarer 10010C 0000000 00000000... 9000004 oo00cs3s 2900000 o000nNND ar noo00n 


SYSCTLG 





Figure 14. Example of a SYSCTLG Dump 
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The data portion of each block begins with a 16-bit binary number that tells how 
many bytes of the block are used (including the two bytes of this number). The 
catalog entries begin immediately thereafter. These entries are described in detail 
in the chapter ‘‘Data Areas.” 


The first entry of the first block is always the volume index control entry (VICE). 
The type of each entry can be determined from the byte at offset 11 of the entry; 
the type codes are described under the field TYPE on page 69. 





Environment Record 


Some error conditions cause an environment record to be written, whenever 

possible, to the last block of SYSCTLG. The environment record is written when a 

non-locate function is requested and the exceptional return code is 8 or 28. Here’s 

how you can dump the catalog and examine this record to see what happened: ‘ 


1. Reproduce the failure, but this time reserve the data set SYSCTLG for your 
exclusive use, so that no other task can destroy the environment record before 
you can dump it. Do this by adding or modifying your JCL statements to include ” 
a DD statement for SYSCTLG with DISP=OLD. 


2. Add a step to your job to dump SYSCTLG. Follow the instructions under 
“SYSCTLG Dump.” 


3. Look at the VICE, which begins at offset two of the first physical block of the 
catalog. (Remember to allow for the key.) Field VCLSTBLK (offset 12 bytes in 
the VICE) contains the TTR for the last block in SYSCTLG. This block contains 
the environment record. 


4. Compute the absolute track address by using the cylinder-head numbers 
supplied for the first block and the TTR. TT is the relative track from the first 
block; R is the record number for that track. 


5. The fields of the environment record are described in ‘‘Environment Record 
(EREC DSECT),” on page 66. The description for each field relates this 
information to other data areas. 


The field ERMODMAP contains seven bits that show which modules have been 
entered. 1GC0002F and iGGOCLCO are always entered; there are no bit switches for 
those modules. 


As an example, if ERMODMAP equals X‘66’, then modules 1GC0002F, IGGOCLCO, 
IGGOCLC2, IGGOCLC3, IGGOCLC6, and IGGOCLC7 were entered during the request 
that caused the environment record to be written. This is the sequence of modules 
that normally occurs with a request for BLDX. 





Note: The environment record is not written for any error associated with a 
‘“catalog-full’”’ condition. 


Module Selection Charts 


Figure 15 can help you determine which modules of the catalog management 
routines are involved in any given situation. The figure consists of several charts, 
which are modified reductions of Figure 10, found on page 26 Each chart shows 
the path through the catalog management routines for the functions noted on that 
chart. Figure 10 does not show the preprocessing done by the Controller. The 
blocks that are used are shaded. The specific path is shown by a bold arrow. 
Always enter module IGGOCLCO, which is the first load of the OS/VS catalog (upper 
left), then move down and to the right. 
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Page number references for flowcharts and module discussions are: 


Page 
Module Name Number 
IGC0002F, Controller | 32 
IGC0002F, Controller II 34 
IGGOCLCA 36 
IGGOCLCB 38 
IGGOCLCO 4() 
IGGOCLC1 42 
IGGOCLC2 44 
IGGOCLC3 46 
IGGOCLC4 48 
IGGOCLCS 50 
IGGOCLC6 52 
IGGOCLC7 54 
IGC0002H 56 
IGGOCLF2 58 
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Locate Relative GOG Name 
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{ Figure 15. Correlating Functions to Modules of Catalog Management 
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Glossary 


This glossary contains definitions of words and acronyms that 
are used in this publication. Other data processing definitions 
can be found tn Data Processing Glossary, GC20-1699. 


alias: An alternative name for a data set. Only the high-level 
name of a qualified data set name may have an alias. 


CAMLST: An Assembler language macro instruction that 
produces the parameter list for catalog management. 


catalog: (noun) The collection of all data set indexes maintained 
by data management. (verb) To include the volume 
identification of a data set in the catalog. 


CATALOG: An Assembler language macro instruction used to 
invoke the catalog management routines. 


cataloged data set: A data set that is represented in an index or 
hierarchy of indexes that provides the ineans for locating the 
data set. 


communication vector table (CVT): An operating system control 
block that provides the address of information in the nucleus to 
non-resident routines. 


connected: The property of a control volume that allows it to be 
found by searching another control volume. 


control volume (CVOL): A volume that contains one or more of 
the indexes of the catalog. 


data control block (DCB): An operating system control block that 
describes the current use of the data set. 


data extent block (DEB): A control block that describes the 
physical attributes of the data set. 


data set: The major unit of data storage and retrieval in the 
Operating system. 


data set control bleck (DSCB): A label for a data set on a direct 
storage volume. 


data set name: An identifier that unambiguously names a data 
set. 


data set pointer entry (DSPE): A catalog entry that identifies the 
volume on which a named data set resides. 


dequeue: To remove a request for a resource from a list of 
requests. 


enqueue: To build a list of requests for a named resource. 

entry: A logical record of the catalog, data set SYSCTLG. 
environment record: A 256-byte record that is written when the 
catalog management routines discover an error. This record, 
which contains significant data that is present at the time of the 
error, iS written to the last block of data set SYSCTLG for later 
analysis. 


generation: One member of a generation data group. 


generation data group (GDG): A collection of historically related 
data sets. 


generation index: An index of the catalog that identifies the 
generations of a generation data group. 


generation index pointer entry (GIPE): A catalog entry that 
identifies a generation index. 


high-level name: The first component of a qualified name. This 
name is found in a volume index of the catalog. 


index: A table in the catalog structure that is used to locate data 
sets. 


INDEX: An Assembler language macro instruction used to 
invoke the catalog management routines. 


index control entry (ICE): The first entry of each index of the 
catalog. This entry contains all control information about the 
index. 


index link entry (ILE): The last entry of each block of the catalog, 
used to link blocks of one index together in a chain. 


index pointer entry (IPE): A catalog entry that attaches a 
lower-level index to the index in which it is found. 


level: A conceptual relationship between indexes of the catalog. 
The index corresponding to the simple name of a data set is said 
to be the lowest level; the first component of a qualifier name is 
said to correspond to the highest-level index. 


locate: Pertaining to functions that do not change the status of 
the catalog; that is, read-only operations are performed on the 
catalog. 


LOCATE: An Assembler language macro instruction used to 
invoke the catalog management routines. 


must-complete: A facility of the operating system that ensures 
integrity whenever system resources are manipulated to modify 
information that is critical to the continued operation of the 
system. 


non-locate: Pertaining to functions that change the status of the 
catalog; that is, write operations are performed on the catalog. 


partitioned data set directory: The portion of a partitioned data 
set that provides a means of locating any of the members of the 
data set. 


qualified name: A data set name consisting of a string of names 
separated by periods; for example, ‘‘TREE.FRUIT.APPLE” isa 
qualified name. 


qualifier: Each component name in a qualified name other than 
the rightmost name. For example, ““TREE” and “FRUIT” are 
qualifiers in‘“*TREE.FRUIT.APPLE”. 


relative track address (TTR): A direct-access device address, 
expressed as a displacement in a data set. This address has the 
form TTR, where TT represents two hexadecimal digits 
specifying the track relative to the beginning of the data set, and 
R is one hexadecimal digit specifying the record on that track. 


resource: Any facility of the computing system or operating 
system required by a job or task, including main storage, 
input/output devices, the central processing unit, data sets, and 
control processing systems. Three unique resources are used by 
catalog management routines: the volume index, high-level 
name, and the volume index control entry (VICE). 


ripple: Displacing data from one block of a chain to the next, 
due to modification of data in a preceding block. 
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simple name: The rightmost component of a qualified name. For 
example, APPLE" is the simple name in 
“TREE.FRUIT.APPLE”. The simple name corresponds to the 
lowest index level for the data set name. 


supervisor request block (SVRB): An operating system control 
block containing program status information and general 
register contents. 


SYSCTLG: The data set name of the catalog. 


system residence vohame: The volume on which the nucleus of the 
operating system and the highest level of the catalog are located. 


task control block (TCB): An operating system control block that 
contains information and pointers associated with the task in 
progress. 

transient area: An area of main storage contained within the 
operating system nucleus where supervisor routines may be 
temporarily loaded for execution. 


true name: The high-level qualifier to which an alias is related. 
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uncatalog: To remove the volume identification of a data set 
from the catalog. 


volume control block (VCB): A block of the catalog that identifies 
as many as 20 volumes containing one data set. 


volume control block pointer entry (VCBPE): A catalog entry that 
identifies a VCB for a named data set. 


vohame index: The highest level of index in the catalog structure. 
Entries in the volume index point to all lower indexes and 
simple names. 


volume index control entry (VICE): The first entry in the volume 
index. The VICE describes the volume index and controls space 
allocation in SYSCTLG. 


volume table of contents (VTOC): A table associated with a direct 
access volume that describes each data set on that volume and 
identifies all available space on the volume. 


J 





index 


The entries in this index are shown as they appear in the text 


of the book, that is, capitalized words are capitalized in text, 
lowercase words are lowercase in text, etc. When more than 
one reference is given for an entry, the primary reference is 


listed first. 


A 
ABEND dump . . 
absolute name 
complemented 
generation data group : 
absolute track addresses to relative, conversion 
ADDING data field 
adding entries 
address conversion, track 
aids for diagnosing . 
alias 
WARICE eos OR ae “Ae eS i oe ee ch, 
number of 
resolution . 
Alias Entry (AE). . . 
ALIASNAM data field ..........020. ; 
AMASPZAP, use with catalog management... . 


B 
BALREGS data field . 
base register . . . 
BASESAVE data field 
BLDA function. . 
BLDENTRY routine in 1 IGGOCLC4 
BLDG function 
BLDL macro instruction. 
listed in program organization 
in method of operation 
BLDLAREA data field 
BLDLCNT data field . 
BLDLIST data field ........202.2. 
BLDLISTP data field . . . 
BLDX function 
BLOCK function . 
blocks 
chaining ...... 
contiguous ‘ 
how chained together: 
multiple os 
relation to index levels ets 
Use OF Key: “3 bea Weeds BA le ke ES 
BLVCBRTN routine in . IGGOCLCS 
building anewentry ........ 
bytes and alignment of data areas 


C 
CALLBLDL routine 
in IGGOCLCI.......2.20222220 2... 
inflGGOCLC2.. . 
relation to BLDL . ne 
CAMCVOLP data field ......... bn tk Ae iw’ Be 
CAMDSCBP data field ........2..202.2. 
CAMGEN data field ...........2.2. 
CAMLST macro instruction . . 
CAMLSTD DSECT, data area 
CAMOPTN | data field . . 
CAMOPTN2 data field 
CAMOPTN3 data field . 
CAMPTRI data field ..........2.22. 
CAMPTR3 data field ..... 
CAT function ..... 
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14 


28 
71 
52 
28 
73 


13 
13 
42 
62 
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catalog data set 

(see also SYSCTLG) 

dump of 

introduction . 
catalog entries , 2 3 
CATALOG macro instruction od 
catalog management 

design of . 

functions of . 

input to ; 

macros and services used . 

output from . 

overview of . 

phases in 
catalog residence . 
CATBX 

function : . % 

method of operation eH 
chaining 

blocks together 

method of operation . . 
Character Dependency 

collating sequence. . 

Communication Vector Table (CVT) . 
complementing absolute names 
connected control volume ... . 
constructing DSPE or VCBPE . 
constructing new entries 
contiguous blocks 

in description of index levels 

method of operation. . . 
control volume (CVOL) 

connected . 

introduction. . . 

opening 

specifying . ‘ 
Control Volume Pointer Entry (CVPE) . Bre. dB Bn Be eo 
Controller module (I1GC0002F) 

Controller]... .. 

Controller {] 
conversion of track addresses 
core storage (see main storage) 
correlating functions to modules . . 
CVOL (see control volume) 
CVT DSECT macro instruction .......2.2... 
CVTPBLDL, reference to . . 
CVTPCNVT, reference to. . 
CVTPRLTV, reference to . 
CWAP data field . 


D 


Data Areas 
descriptions . . 
format of . 
hierarchy . . 
data control block (DCB) 
definition . . ; 
modifications to . 
use with catalog management . isfy, safes 
DATA data field... ......2.224. 
data extent block (DEB) 
modifications to. ......2.2.2.2.2.2848 
use with catalog management . 
data set control block (DSCB) 
use with catalog management... . 
dataset name .. : 
data set pointer entry (DSPE) 
constructing . 
entry description 
format 


Index 
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DCB (see data control block) 


DCBADDR datafield ..............0.. 71 
DEB (see data extent block) 
DEBADDR datafield .............2... 71 
DELETE option of generation data group ....... 48 
deleting entries 

method of operation... ........2...244 21 

module description ..............0.- 52 
dependency, character .............244.4. 29 
DEQ macro instruction... ......2.2..2.... 29 
dequeue, definition... ............2.284. 79 
description of catalogentries ........2...2.2.. 14 
design of catalog management... .......2... 17 
DEVTYPE data field .............2.4.2.-,. 71 
Diagnostic Aids ........ 1... eee ee ee 73 
directory, microfiche ..............24842-, 60 
DLTA function ...... 2.2... 2 eee ee eee 16 
DLTX function ....... 2.2... 2. 2. ep eee 16 
DRPX function ............ 20282808. 16 


DSCB (see data set control block) 
DSECT macro instructions 


ONS 2 ies eit, Bee wasn als ae we a ee a ye a Tex ee 29 
IEFUCBOB... 6. 2 6..6 3a ee eS Ae Ba 8 RS SG 29 
DSNAME data field .............2.2.2.. 72 
dump 
environment record .........2..2.2.2.2.428-. 76 
main storage ......... 20. 2 ee ee eee 73 
SYSOTEG % & 2. Bie Me cae Rh Writ Gi ow as WS SS 74 
E 
ECB datafield. ................... 72 
EDATA data field .................. 63 
EDEVTYP data field ...............2.4.. 62 
EDSCBTTR data field ..............2.. 63 
EGCURSIZ datafield ..............2.. 63 
EGFLAGS data field ................. 63 
EGMAXSIZ data field ...........2..4.2. 63 
EMPTY option of generation data group ........ 50 
EMPTYRTN routine inIGGOCLCS .......... 51 
ENAME data field 
elias Cntry” sh ac ceener ewe ad Sa es S ROK 62 
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